Skip to content
LabTether

Connector Sync Failures

A connector test fails, sync returns errors, or discovered assets are missing. The connector health indicator shows red or degraded in the console.

Auth errors

Authentication problems are the most common cause of connector failures.

Symptoms: The connector test returns auth denied, unauthorized, or 403.

Check these first:

  • Credential rotation. If the upstream platform's API token or password was recently rotated, the connector still has the old value. Update the connector credentials in the console and re-run the test.
  • Token expiration. Some platforms issue time-limited tokens. If the connector was working last week but fails today, the token may have expired. Generate a new one on the upstream platform and update the connector.
  • Insufficient scope. The API token may exist and be valid but lack the permissions the connector needs. For example, a Proxmox token without PVEAuditor role cannot enumerate VMs. Check the connector documentation for required permissions and compare against what the token actually has.

Tip: After updating credentials, always run the connector test before triggering a full sync. The test validates authentication and basic connectivity without the overhead of a full discovery cycle.

Network errors

If the connector test fails before it even gets to authentication, the problem is network-level.

Wrong URL or port. Double-check the connector endpoint URL. Common mistakes:

  • Using http:// when the platform requires https://
  • Wrong port number (Proxmox uses 8006, TrueNAS uses 443 or 80 depending on configuration)
  • Hostname that does not resolve from the hub's network context

TLS certificate mismatch. If the upstream platform uses a self-signed or private CA certificate, the hub will reject the TLS handshake by default. Options:

  • Install the upstream platform's CA certificate in the hub's trust store
  • For development/testing only, set LABTETHER_ALLOW_INSECURE_TRANSPORT=true

Warning: Do not leave LABTETHER_ALLOW_INSECURE_TRANSPORT=true in production. It disables TLS verification for all connectors.

Firewall or ACL changes. If the connector was working before but the endpoint is now unreachable, check whether firewall rules, network ACLs, or security groups changed on either side.

Test connectivity from the hub host:

# From the hub host or container
curl -sk https://<platform-host>:<port>/api/version

If this times out, the problem is between the hub and the upstream platform, not in LabTether.

Partial discovery

The connector test passes and sync completes, but some assets are missing from inventory.

Account visibility. The API user or token may only have visibility into a subset of the platform. For example:

  • A Proxmox token scoped to one pool will not see VMs in other pools.
  • A Docker connector using a socket mounted from one Docker host will not see containers on other hosts.
  • A Portainer token with limited endpoint access will only discover containers on those endpoints.

Fix this by broadening the API token's access scope on the upstream platform, or by creating separate connectors for each scope boundary.

Sync status: partial. If a sync completes with a partial status, the connector encountered errors partway through discovery but still returned what it could. Check the sync details in the console for specific error messages -- they usually point to individual resources that failed to enumerate (for example, a single VM whose configuration could not be read).

Per-platform gotchas

Proxmox

  • The API token needs at least PVEAuditor permissions on / to see all nodes and VMs.
  • Token format is user@realm!tokenid with the secret as a separate field.
  • Self-signed certificates are common; you may need to handle TLS trust as described above.

TrueNAS

  • SCALE and CORE use different API versions. Confirm you have selected the right variant when creating the connector.
  • WebSocket endpoints (ws:// / wss://) follow the same insecure transport rules as HTTP endpoints.

Docker

  • Unix socket endpoints (/var/run/docker.sock) are local IPC and do not require insecure transport configuration.
  • If you see insecure-scheme errors for a Docker connector, confirm the endpoint is set to a socket path, not an http:// URL.
  • Remote Docker hosts over TCP need TLS configured on both the Docker daemon and the connector.

Home Assistant

  • Long-lived access tokens are created in the HA user profile, not in the integration settings.
  • The token must belong to a user with admin privileges to see all entities.

Portainer

  • API tokens are generated under user settings. Admin-level tokens see all endpoints; non-admin tokens see only assigned endpoints.