Troubleshooting

The binary will not start

Check that all seven security-sensitive paths are absolute, distinct, and writable by the runtime user. By default they live under ~/.dataporch; if you use a checkout, container, or system layout, export all seven DATAPORCH_*_PATH overrides before secrets init and before starting the server.

The command prints help instead of starting

That is expected. Bare dataporch is command discovery and no longer starts a long-running process. Use dataporch run -f for foreground execution or dataporch run for the native per-user service.

The background service is unavailable

Native background lifecycle requires launchd on macOS or systemd --user on Linux. Use dataporch run -f with another operating system, a container, CI, or an external supervisor.

The service is stopped after an upgrade

Re-register the service with the newly installed executable:

dataporch restart

If the service has not been registered yet, run dataporch run first. restart does not create state or recover an uninitialized installation.

The local plugin cannot connect

Confirm that dataporch run is still running and that the plugin can invoke dataporch mcp. The adapter requires the owner-only socket and runtime credential under the configured DATAPORCH_MCP_SOCKET_PATH and DATAPORCH_MCP_CONTROL_TOKEN_PATH. A health response proves only that the HTTP listener is alive; it does not prove that the local MCP transport is available.

Direct HTTP MCP returns unauthorized

Confirm the client uses /mcp, not /, and that DATAPORCH_MCP_TOKEN contains the current token created by dataporch mcp-token create or rotate. The direct HTTP endpoint uses the long-lived token verifier; it is separate from the runtime credential used by dataporch mcp.

The source does not appear

Import through the local admin socket and confirm the command used the same socket path as the running process. Source IDs are exact. If the import failed, check the URL shape and selected --kind. Import does not test database connectivity; if a later schema, table, or query operation fails, check database availability and permissions.

Discovery returns no matches

Search is a case-insensitive literal substring. Use the source ID returned by data_source.list, then the exact schema from list_schemas, then the exact relation from list_tables. Do not guess quoted or case-sensitive names.

A query is truncated or times out

Inspect truncated and row_count. Narrow the query, request fewer columns, add a predicate, or paginate at the application level. The server caps timeout at 20 seconds and defaults to 1,000 rows and a 10 MiB encoded response.

The plugin appears twice

Remove duplicate dataporch installations from the client and reinstall one source. A stale plugin can also keep an old tool description; restart the client after updating.

Rotate or revoke a direct HTTP token

dataporch mcp-token list
dataporch mcp-token rotate
dataporch mcp-token revoke

Use --yes for non-interactive revocation. After rotation, update the direct HTTP client environment; after revocation, remove the token from the client process. Local plugin credentials rotate with the runtime and do not use these commands.