Skip to main content

Common StackQL Errors

Most StackQL failures fall into five categories: missing providers, missing required parameters, authentication problems, provider-side limits, and gated operations. Each has a fast diagnostic.

Provider or table not found​

Symptom: a query references aws.ec2.instances (or any resource) and fails to resolve the provider or table.

Cause: provider definitions are not bundled; they are pulled per machine from the registry.

Fix:

SHOW PROVIDERS;          -- what is installed
REGISTRY LIST;           -- what is available
REGISTRY PULL aws;       -- install (repeat per provider)

Provider versions are also listed by REGISTRY LIST - re-pulling upgrades to the latest published spec.

Missing required parameters​

Symptom: a syntactically valid SELECT fails or returns nothing because a required parameter (commonly region, subscriptionId, project, org, or a parent resource identifier) was not supplied.

Cause: the underlying API operation has required routing parameters; StackQL surfaces them as required WHERE predicates.

Fix: discover the requirements, then supply them as equality (or IN) predicates:

SHOW METHODS IN aws.ec2.instances;

The RequiredParams column tells you, per access method, exactly what the WHERE clause must contain - for aws.ec2.instances the describe method requires region. This discovery step is the documented practice for both humans and agents (the MCP server publishes the same data through list_methods).

Authentication failures​

Symptom: metadata commands (SHOW, DESCRIBE) work, but SELECT or mutations fail with provider 401/403 errors.

Cause: metadata is served from local provider specs and needs no credentials; data operations call the provider. The credentials are absent from the process environment, misnamed, or insufficient.

Fix: verify the variables are exported in the environment that launched StackQL (a server or MCP process inherits its launch environment - restarting it after setting variables is a common miss), the names match the provider convention (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRET, GOOGLE_CREDENTIALS, STACKQL_GITHUB_USERNAME/STACKQL_GITHUB_PASSWORD), and the principal has the permissions the operation needs. The per-provider how-tos under /ai/how-tos cover each convention.

GitHub rate limiting​

Symptom: unauthenticated GitHub queries work briefly, then fail.

Cause: GitHub's unauthenticated limit is 60 requests per hour per IP, and one StackQL query can issue multiple paginated API calls.

Fix: authenticate with a personal access token (even a no-scope token raises the limit substantially) - see How to authenticate StackQL to GitHub.

Empty results that should not be empty​

Symptom: the query succeeds but returns zero rows for resources you know exist.

Checklist: the routing predicates point at the right scope (correct region, project, subscription, or org); the access method selected by your predicates is the one you intended (SHOW METHODS shows which predicate combinations select which method - for example org = versus username = on github.repos.repos); and the credential can see the resources (cloud IAM can filter list results silently).

MCP mutation refused​

Symptom: an agent's INSERT/UPDATE/DELETE through the MCP server is refused, mentioning elicitation or the server mode.

Cause: this is the safety contract working, not an error. The default safe mode requires human approval for mutations; clients that do not advertise the MCP elicitation capability cannot grant it.

Fix: use an elicitation-capable client (Claude Desktop, Cursor, Continue) and approve the prompt, or - for trusted, non-interactive automation only - run the server with "mode": "full_access". Details in StackQL MCP Architecture.