Troubleshooting

serve --locked Says Prepared Artifacts Are Missing Or Stale

Run:

gestaltd init --config ./config.yaml

Then start again with:

gestaltd serve --locked --config ./config.yaml

config validation: server.encryption_key is required

Set server.encryption_key whenever auth.provider is not none.

/mcp Is Not Mounted

Check that at least one integration exposes tools. Inline declarative operations, OpenAPI, GraphQL, upstream MCP, and MCP-enabled packaged providers all qualify.

An Integration Requires An Explicit Connection

This means the integration has more than one possible connection and no default. Set one of:

• plugin.default_connection
• _connection on the invocation request
• --connection in the client CLI

A Call Fails With An Ambiguous Instance Error

The user has more than one stored instance for that integration and connection. Specify:

• _instance in the HTTP request
• --instance in the client CLI

A Managed Path Parameter Still Appears In The Operation

Make sure the operation path actually contains the placeholder.

Valid:

path: /workspaces/{workspace_id}/tickets

Invalid:

path: /workspaces/tickets

/ready Returns 503

Readiness stays false until:

• providers finish loading
• the datastore answers a ping

Check server logs for provider bootstrap errors or datastore connectivity problems.