Skip to main content
Start with the quick checks, then open the entry that matches what you see. Run the PowerShell commands on the agent computer.

​
Quick checks

In Omnilinker, open ERP Integration > Connections, open the connection and check its Agent tab. See Monitoring.
  • isConnected: False: the agent cannot talk to Omnilinker, or Omnilinker rejects it.
  • isErpConnected: False: the agent cannot read the ERP database.
  • pending growing in the outbox stats: changes are detected but not delivered.
The status fields are described in the local API reference.

​
Common problems

The agent has two logs.Service log files. The Windows service writes one file per day and keeps the last 30:
That is usually C:\ProgramData\Omnilinker\ErpSync\logs. Everyone signed in to the computer can read it. To follow today’s file:
In the tray app, View Logs > Open Log Folder opens the same folder.Setup log. Setup, updates and uninstalling write what they could not do to setup.log in the same folder. See Setup finished, but there is no service.Sync log. The agent also keeps a short log of sync events in its local database. Read it in the tray app with View Logs, or with GET /api/sync/logs on the local API.The agent does not write its own messages to the Windows event log. Windows records service start failures in the System log (see the next entry).
Get-Service OmnilinkerErpSyncService shows Stopped, or the service stops shortly after it starts. The tray app shows Disconnected in its tooltip.The service is set to restart itself after a failure (after 5, 10 and 30 seconds), so a service that keeps stopping has a problem that a restart does not fix.
  1. Open Event Viewer > Windows Logs > System and look for errors from the source Service Control Manager that name Omnilinker ERP Sync (Omnilinker ERP Sync Service on an installation made with install-service.ps1). For a crash, also check Windows Logs > Application for .NET Runtime or Application Error entries.
  2. Open the newest service log file (see Where are the logs?). If the service started far enough to log, the last lines say why it stopped. A fatal start-up error ends with Omnilinker ERP Sync Service terminated unexpectedly.
Common causes:
  • Logon failure. Someone changed the service to run under another account, and its password changed. The System log says the service did not start due to a logon failure. Open Services, open Omnilinker ERP Sync > Log On, select Local System account and click OK. The agent is designed to run as Local System.
  • Port 5555 in use. See The local API port is already in use.
  • Broken appsettings.json. If you edited it, check that it is still valid JSON. From the install folder:
    An error means the file is not valid. Fix it or restore it from the original package.
Start the service again after a fix, in PowerShell as Administrator:
Setup completed, but Get-Service OmnilinkerErpSyncService finds no service, or the tray app does not start at sign-in. Setup never fails because of one step; it writes what it could not do to %ProgramData%\Omnilinker\ErpSync\logs\setup.log:
If there is no setup.log at all, setup could not even create the folder. Run it again from PowerShell as Administrator.
The tooltip says Disconnected, or the setup wizard shows “Failed to connect to service”.
  1. Check that the service is running: Get-Service OmnilinkerErpSyncService. If it is not, see The service does not start.
  2. If the tray app shows “Something other than the Omnilinker service answered. Restart the PC; if it happens again, contact support.”, another program answered on the agent’s pipe. The tray app talks only to the Windows service. Restart the computer.
You can see the agent’s status, but saving settings, the setup wizard, pausing or enabling change tracking fails with “Only an administrator of this PC can do that.”Your Windows account is not allowed to change the agent. Ask an administrator of the computer to add you to the local group Omnilinker ERP Sync Operators, then try again. You do not need to sign out. See Who can change the agent.An administrator can also exit the tray app and start it again with Run as administrator.
A script or monitoring tool gets 403 Forbidden with an empty body from http://localhost:5555/api/....
  • Add the header X-Omnilinker-Local: 1 to every request. See Local API.
  • Call the API as localhost, 127.0.0.1 or [::1], not by the computer’s name.
  • From a web page, only Omnilinker’s own pages may call the API.
The service stops right after it starts. Its log file contains a line like Failed to bind to address http://127.0.0.1:5555: address already in use.Another program uses port 5555 on the agent computer. Find it:
Stop that program or move it to another port, then start the service.You can move the agent to another port with LocalApiPort in appsettings.json, but the web app’s Local Service tab and the tray app’s fallback connection keep using port 5555 and will not reach the agent. Free port 5555 if you can. See the configuration reference.
Offline means Omnilinker has not received a heartbeat for more than 3 minutes. Last heartbeat shows when the last one arrived. A running, accepted agent sends one every 60 seconds.Work through these in order:
  1. Is the service running? See The service does not start.
  2. Can the agent reach Omnilinker? See The agent cannot reach omnilinker.pl.
  3. Is the connection active? On ERP Integration > Connections, the connection’s Status must be Active. Omnilinker rejects heartbeats and changes for an inactive connection. To switch it on, click Activate in the row’s Actions menu.
  4. Is the API key still valid? See The API key is rejected.
  5. Is the agent too old? See Omnilinker rejects the agent version.
If the tab says No agent has connected yet, the agent has never reached Omnilinker with this connection’s key. Complete the setup wizard on the agent computer.
The agent’s log shows, repeatedly:
In the tray app, validating the key shows “Invalid API key. Please check and try again.”The agent’s key no longer works. Most often someone clicked Generate Agent Key on the connection again: generating a new key revokes the previous one straight away.To fix it:
  1. In Omnilinker, open ERP Integration > Connections, open the row’s Actions menu and click Generate Agent Key. Copy the key. It is shown only once. See Create a connection.
  2. On the agent computer, open the tray app’s Settings…, paste the key under Cloud Connection, click Validate, then Save. See Tray app.
Generating a key again revokes the one you just made too, so do it only once and store the new key in the agent straight away.Two related messages:
  • “API key doesn’t have required permissions. Grant ERP Integration permissions to this API key.” The key is not an agent key. Use a key from Generate Agent Key, not one from the Administration API keys page.
  • “This agent key is not authorized for the requested ERP connection.” The key belongs to a different connection. Select the right connection in the tray app’s settings, or generate a key on this connection.
Status: Forbidden in the first message above is not a key problem. See Omnilinker rejects the agent version and Changes are not arriving.
Omnilinker can require a minimum agent version. When your agent is older, Omnilinker rejects every request from it with:
What you see:
  • In Omnilinker, the connection’s Agent tab turns Offline and Last heartbeat stops moving. Agent version still shows your old version.
  • In the agent’s log, Heartbeat returned Forbidden, and Cloud API returned Forbidden for batch publish: followed by the message above. The configuration check also logs Authentication failed ... Status: Forbidden, even though the key is fine.
  • The outbox pending count grows, and later failed grows too.
The agent updates itself at night when a newer version is published, so this should clear by itself. If it does not, check that automatic updates are on (AutoUpdateEnabled) and that the agent computer can reach releases.omnilinker.com, or run the new installer by hand.Do it promptly. Each rejected send counts as a failed attempt, and changes that fail every attempt are not sent again (see Changes are not arriving).
The status shows isConnected: False. The tray app’s cloud connection test fails with Cloud connection failed: followed by the reason, or Cloud returned status: followed by an HTTP status.
  1. Test the connection from the agent computer:
    TcpTestSucceeded : False means a firewall or the network blocks it. The agent needs outbound HTTPS to omnilinker.pl on port 443. See Requirements.
  2. If your network requires a proxy, set it for the machine with the HTTPS_PROXY environment variable, then restart the service. The service runs as Local System, so it does not use the proxy settings of the person signed in:
  3. Check the API URL in the tray app’s Settings…. It should be https://omnilinker.pl.
While Omnilinker cannot be reached, the agent keeps working from its last downloaded configuration and keeps queuing changes. But every failed send counts as an attempt, so a long outage can make queued changes fail for good. See Changes are not arriving.
The status shows isErpConnected: False, or the tray app’s Test Connection shows SQL error: followed by SQL Server’s message.Test the database settings in the tray app: Settings… > Database Connection > Test Connection. The test runs inside the Windows service, with the service’s account, so it behaves the same way as the agent.The server cannot be found. SQL Server’s message starts with “A network-related or instance-specific error occurred while establishing a connection to SQL Server”.
  • Check Server / Host. For a named instance use server\instance, for example erp-server\WAPRO.
  • Check that the agent computer can reach the SQL Server port:
    Use your instance’s port if it is not 1433. A named instance with a dynamic port also needs the SQL Server Browser service and UDP port 1434.
Login failed. SQL Server’s message starts with “Login failed for user”.
  • SQL Server authentication (a Username is filled in): check the username and password, and that SQL Server allows SQL Server authentication (mixed mode).
  • Windows authentication (Username left empty): the agent logs in as the service’s account, Local System, not as you. The user named in the message is that account: the agent computer’s domain account (DOMAIN\COMPUTER$) on a remote SQL Server, or NT AUTHORITY\SYSTEM on SQL Server on the same computer. Give that account a login and read access to the ERP database, or use SQL Server authentication. See Requirements.
  • Check that the login can open the database named in Database Name.
Certificate errors. SQL Server’s message mentions the certificate, for example “The certificate chain was issued by an authority that is not trusted”.The agent encrypts the connection to SQL Server by default, even when Encrypt connection is not ticked, and most SQL Server installations use a self-signed certificate. Either install a certificate on SQL Server that the agent computer trusts, or tick Trust server certificate under Advanced Connection Options and click Save.
Test Connection uses the two check boxes exactly as ticked, while the service encrypts unless told otherwise. So the test can pass with both boxes unticked while the service still fails with a certificate error. If you see that, tick Trust server certificate.
The agent detects changes but Omnilinker does not receive them. GET /api/sync/outbox/stats shows pending growing, or failed above zero. The tray menu shows Queue: <n> pending | <n> failed.How the agent retries. The agent keeps every change in a local outbox and sends it in batches every few seconds. When a send fails, for any reason, the change stays pending and is tried again in the next cycle. After 5 failed attempts (MaxRetryAttempts in appsettings.json) it is marked failed and the agent does not send it again.Find the reason in the agent’s log file. Look for:Also check that the connection is Active in Omnilinker.Changes that have already failed every attempt are not sent again automatically. A later change to the same record in the ERP is detected and sent as usual.
The Agent tab says Online, but no new sync log entries appear in Omnilinker.Check, in order:
  1. Is syncing paused? The tray icon is amber and the tooltip says Paused, or the status shows state: 2. Select Resume Sync in the tray menu. See Tray app.
  2. Is the entity type configured? On the connection’s Sync Configuration tab, each entity type you want to sync needs a configuration that is Enabled. If the tab says “No sync configurations found. Add one to enable synchronization.”, add one. See Sync configuration.
  3. Is change detection on? With hash scan change detection (the default), the agent finds changes only with hash checks. Open the Product sync configuration, expand Advanced Timing Settings and make sure Hash-Based Change Detection is Enabled. In the tray menu, Hash Check: Disabled means it is off.
  4. Has the agent loaded its configuration? If lastError is Waiting for cloud configuration, the agent has not yet downloaded its settings from Omnilinker. See The API key is rejected and The agent cannot reach omnilinker.pl.
  5. Are the ERP credentials set? If lastError is ERP credentials not configured, or the tray app’s ERP test says “No ERP credentials configured. Run setup wizard to configure.”, complete the setup wizard.
  6. Has anything changed in the ERP? The agent sends only changes. The first hash check after installation compares every record; later ones find only what changed since. To check now, select Trigger Hash Check in the tray menu.
A hash check runs on its interval (15 minutes by default). Sync Now in the tray app starts one sooner.
Sync log entries in Omnilinker show no status badge, and their error message is a code such as ErpIntegration:Skip:ProductNotMapped. Omnilinker received the change but did not apply it on purpose.Most of these mean something is not mapped yet:
  • ErpIntegration:Skip:PriceLevelNotMapped or ErpIntegration:Skip:WarehouseNotMapped: map the ERP price level or warehouse on the connection’s Mappings tab. See Reference items.
  • ErpIntegration:Skip:ProductNotMapped: the price, stock or bundle belongs to a product that is not linked to a catalog product yet. Make sure products sync first. See Field mappings.
The full list is in Monitoring.
Test Connection in a connection’s Actions menu always reports a failure. That is expected: Omnilinker does not have your ERP database credentials, which stay on the agent computer. Test the database connection in the tray app instead: Settings… > Database Connection > Test Connection.
Trigger Sync on the connection page (and the sync button on the dashboard) confirms “Synchronization has been triggered”, but it does not reach the agent. Retry on a failed sync log entry only sets it back to Pending.To make the agent look for changes now, use Sync Now or Trigger Hash Check in the tray app, or POST /api/sync/now on the local API. See also Monitoring.
The Local Service tab of a connection talks to the agent at http://localhost:5555 from your browser. It works only in a browser on the agent computer, with the agent on port 5555. On any other computer this message is expected. Use the Agent tab instead. See Monitoring.

​
Get help

If none of this solves the problem, contact Omnilinker support. Include:
  • The connection name, and what you see on its Agent tab.
  • The agent’s version, from the Agent tab or the version field of GET /api/sync/status.
  • The output of the quick checks at the top of this page.
  • The service log files from the time the problem started.
Never send credentials.dat, and do not paste your API key or ERP password into a message. The local API never returns them. Look through the log files before you send them.