Skip to content

Troubleshooting

Use this page when a SchemaDock is offline, a destination connection is denied, an install or upgrade fails, or a routed node behaves differently from Direct.

First checks

Confirm these items in order:

  1. The Dock is Enabled.
  2. Enrollment is Enrolled.
  3. Last seen is recent.
  4. The Dock is authorized for the pipeline organization.
  5. The node uses the intended Connection Route.
  6. Destination policy permits the requested host and port.
  7. The SchemaDock host can resolve and reach the private destination.

Linux service checks

Check status:

systemctl status schemadock --no-pager -l

Check recent logs:

journalctl -u schemadock --since "30 minutes ago" --no-pager -l

Check the installed version:

/usr/local/bin/schemadock version

Restart only when required for troubleshooting or after configuration changes that explicitly require it:

sudo systemctl restart schemadock

Windows service checks

Use Windows Services to confirm the SchemaDock service is running.

Where permitted, PowerShell can be used:

Get-Service -Name SchemaDock

Check the installed version:

& "C:\Program Files\SchemaDock\schemadock.exe" version

Dock is offline

Common causes include:

  • outbound TCP 443 to the SchemAlign gateway is blocked
  • DNS cannot resolve the SchemAlign gateway
  • local service is stopped
  • enrolled identity files were removed or replaced
  • temporary gateway or upstream availability issue

SchemaDock uses reconnect/backoff behavior. A temporary gateway interruption may produce transient WebSocket or 502 Bad Gateway messages before the agent reconnects automatically.

Do not assume a manual service restart is required for every temporary gateway interruption.

Destination denied

A destination may be reachable from the SchemaDock host but still denied by policy.

Check:

  • policy mode is the expected mode
  • an Allow rule matches the destination host or network
  • the requested port is included
  • no matching Deny rule overrides the Allow
  • the Dock is authorized for the pipeline organization

Restricted mode denies requests that do not match an Allow rule.

Destination connection refused or timed out

If policy allows the destination but the connection still fails:

  1. Test DNS resolution on the SchemaDock host.
  2. Test TCP reachability from the SchemaDock host to the destination port.
  3. Confirm the destination service is listening.
  4. Confirm intermediate firewalls permit the connection.
  5. Confirm the destination hostname and port in the node are correct.

SchemaDock does not make an unreachable private destination reachable by itself. The agent host must have normal network reach to the destination.

TLS or certificate errors

For HTTPS and LDAPS, SchemaDock preserves the originating TLS session.

Certificate failures should be investigated as destination TLS/trust problems rather than bypassed in SchemaDock.

Check:

  • destination certificate hostname
  • certificate expiration
  • internal CA trust where required
  • SNI/hostname configuration

Do not disable certificate verification merely to make a private route succeed.

SFTP errors

For SFTP, verify:

  • host and port
  • SFTP account credentials
  • SSH key format and passphrase when used
  • private destination policy
  • remote path permissions

SchemaDock transports the SFTP/SSH session; it does not replace SFTP authentication.

Install or upgrade issues

Linux

A current package should extract with executable install.sh, uninstall.sh, and schemadock files.

Normal installation is:

sudo ./install.sh

Manual CRLF conversion or chmod repair should not be required for SchemaDock 0.1.5 packages.

Windows

Unsigned or low-reputation executables may be blocked by Windows SmartScreen or enterprise endpoint policy.

Do not bypass centrally managed endpoint protection. Work with the endpoint-security administrator when policy prevents execution.

Selected Dock fails but Direct works

This can be expected when the private route has different network, policy, or certificate requirements.

Check the SchemaDock route rather than switching the node silently to Direct.

A configured SchemaDock route intentionally fails closed.

Performance troubleshooting

Before changing SchemaDock transport behavior, determine whether the issue is:

  • destination server performance
  • customer network bandwidth or latency
  • cloud-to-customer latency
  • a chatty serialized application protocol
  • a generic TCP/WebSocket forwarding defect

Do not add protocol-specific SchemaDock behavior merely to optimize one application protocol.