Troubleshooting

Startup

When gestaltd serve --locked reports that prepared artifacts are missing or stale, the lock state has drifted from the current config. Run gestaltd init --config ./config.yaml to re-resolve and re-prepare all references, then start the server again with gestaltd serve --locked --config ./config.yaml.

The validation error server.encryptionKey is required means the config is missing its root deployment secret. Set server.encryptionKey to a structured secret ref or other secret-backed value. The encryption key is used for token encryption and derived session material, so the server refuses to start without it.

Set server.encryptionKey for every real deployment. Gestalt derives token and session encryption from it regardless of which authentication and datastore providers you use.

If the /mcp endpoint is not mounted, the server found no plugin that exposes tools. At least one plugin must surface MCP-visible operations before /mcp becomes available.

When /ready returns 503, the server has not finished initialization. Readiness stays false until all configured providers finish loading and the datastore answers a ping. Check server logs for provider bootstrap errors or datastore connectivity problems.

Operation invocation

A “provider not found” error means the plugin key in the request does not match any entry in plugins. Verify the spelling and confirm the plugin loaded without errors at startup.

An “operation not found” error means the operation ID does not exist in the plugin’s catalog. Check that the operation is exposed and that allowedOperations, if set, includes it.

A “not authenticated” error on an API or MCP request means no valid session or API token was presented. Log in through the UI or pass a bearer token in the Authorization header.

A “no external credential” error means the user has not connected the plugin. Complete the OAuth or manual-auth flow for the provider and connection before invoking operations.

An “ambiguous instance” error means the user has more than one stored instance for that plugin and connection. Pass _instance in the HTTP request body or --instance in the client CLI to select the correct one.

A “token scope denied” error means the operation requires an OAuth scope that was not granted during the connection flow. Disconnect and reconnect the plugin, ensuring all required scopes are approved.

Token refresh failures indicate that the upstream provider rejected the stored refresh token. The refresh token may have been revoked, expired, or rotated by the provider. Disconnect and reconnect the plugin to obtain fresh credentials.

Upstream errors

A “timed out” error means the outbound request to the upstream service exceeded the configured timeout. The upstream may be slow or unreachable. Check network connectivity and consider increasing the timeout if the upstream is known to be slow.

A “failed to reach” error means the outbound connection could not be established at all. Verify that the upstream host is correct, DNS resolves, and any egress firewall rules or sandbox allowlists permit the connection.

Provider Packages

When a provider package fails to start, check that the binary exists at the expected path, is executable, and that any required runtime dependencies are available. Startup errors appear in the server log with the provider name.

Common source-package checks:

Go

Verify the package builds from the provider root:


go build ./...

The source package should include go.mod, manifest.yaml, and provider code at the module root.

Python

Verify the virtualenv is intact and the configured module is importable:


uv run python -c "import provider"

Also confirm the [tool.gestalt].provider entry in pyproject.toml points at the module Gestalt should load.

Rust

Verify the crate builds from the provider root:


cargo check

The plugin root needs a real Cargo.toml package with a [package] section, not just a workspace manifest, and src/lib.rs should export the provider with gestalt::export_provider!(...), gestalt::export_authentication_provider!(...), or gestalt::export_indexeddb_provider!(...).

TypeScript

Verify the module resolves from the provider root:


bun run -e "import('./provider.ts')"

Confirm package.json has a gestalt.provider entry pointing at the correct ./file.ts#export target. The target path must start with ./ and the export name must match a named export in the module.

A sandbox 403 means the provider process made an outbound request to a host not listed in allowedHosts. Add every upstream domain the plugin contacts to the allowlist in the plugin’s config entry or manifest. If the deployment does not support executable-plugin sandboxing for that runtime, you may see startup or provider-load failures instead.

An input decode error means the operation received a request body that does not match the expected schema. Check the operation’s parameter definitions and ensure the caller is sending the correct types and required fields.

Rate limit errors from upstream services are passed through to the caller. The plugin does not retry rate-limited requests automatically. Implement backoff in your client or reduce request volume.

An invocation depth error means a plugin-to-plugin call chain exceeded the maximum allowed depth. This typically indicates a recursive loop where one provider’s operation triggers another that eventually calls back into the first. Break the cycle or restructure the operation flow.

Connections

When a plugin requires an explicit connection, it has more than one configured connection and no default. Pass _connection on the invocation request or use --connection in the client CLI to disambiguate.

If a managed path parameter still appears in the operation schema, the operation path template does not contain the expected placeholder. Verify that the path includes the parameter in braces, such as /workspaces/{workspace_id}/tickets, rather than omitting it.