Skip to main content

Troubleshooting

This page covers common issues you may encounter when using Metatate's canonical MCP layer, Snowflake Intelligence wrappers, the Claude Code plugin, or the Cortex Code plugin.

MCP Server Not Found​

Symptom: SHOW MCP SERVERS IN SCHEMA METATATE_APP.CORE returns no rows.

Cause: The MCP server has not been registered, or registration failed silently.

Solution:

-- Register (or re-register) the MCP server
CALL METATATE_APP.V1.REGISTER_MCP_SERVER();

-- Verify it was created
USE APPLICATION METATATE_APP;
SHOW MCP SERVERS IN SCHEMA CORE;

If registration fails, check that:

  • The APP_WAREHOUSE reference is configured (SHOW REFERENCES IN APPLICATION METATATE_APP;)
  • The app is fully initialized (CALL METATATE_APP.V1.INIT();)

No Governed Tables Returned​

Symptom: discover-context returns { "status": "success", "data": [], "errors": [] } -- success but empty data.

Cause: No governance policies have been deployed, so the governance tables are empty.

Solution:

  1. Open the Metatate UI and create a policy targeting at least one table
  2. Deploy the policy (compile and materialize)
  3. Verify governance tables have data:
SELECT COUNT(*) FROM METATATE_APP.CORE.GOVERNED_TABLES;

If the count is 0, the deployment did not materialize. Check the Metatate backend logs for errors.

Empty Results for a Specific Table​

Symptom: get-decision-context or inspect-data-meaning returns an error or empty data for a table you expect to be governed.

Cause: The table name is not fully qualified, or the case does not match.

Solution:

Always use fully qualified table names in the format DATABASE.SCHEMA.TABLE:

-- Correct
SELECT METATATE_APP.CORE.GET_GOVERNANCE_CONTEXT(
  OBJECT_CONSTRUCT('table_name', 'ANALYTICS_DB.CORE.CUSTOMERS')
);

-- Incorrect (will not match)
SELECT METATATE_APP.CORE.GET_GOVERNANCE_CONTEXT(
  OBJECT_CONSTRUCT('table_name', 'CUSTOMERS')
);

Table names in the governance catalog are stored in uppercase. If you pass lowercase names, the tool normalizes them, but mixed-case quoted identifiers (e.g., "MyTable") may not match. Verify the exact name:

SELECT FULL_TABLE_NAME FROM METATATE_APP.CORE.GOVERNED_TABLES;

Permission Denied​

Symptom: Insufficient privileges error when calling MCP tools, or 403 from the HTTP endpoint.

Cause: Your role does not have the Metatate app roles granted.

Solution:

-- Check which app roles you have
SHOW GRANTS TO ROLE <your_role>;

-- Grant app role if missing
GRANT APPLICATION ROLE METATATE_APP.APP_USER TO ROLE <your_role>;

-- For admin access:
GRANT APPLICATION ROLE METATATE_APP.APP_ADMIN TO ROLE <your_role>;

For Snowflake Intelligence, ensure the role you are using has the Metatate app role granted and can access the agent object you created.

For Claude Code, ensure the role requested by session:role:<snowflake-role> has the Metatate app role granted.

For Cortex Code, ensure the role in X-Snowflake-Role has the Metatate app role granted and matches the PAT ROLE_RESTRICTION.

Claude Code Role ALL Is Blocked​

Symptom: Snowflake OAuth shows:

The role ALL requested has been explicitly blocked for use with this application by an administrator.

Cause: Claude Code requested the user's default role or secondary role ALL instead of the Metatate role allowed by the OAuth security integration.

Solution:

  1. Remove the existing MCP registration:

    claude mcp remove metatate

  2. Register again with an explicit Snowflake role scope:

    claude mcp add-json --scope user --client-secret metatate '{
      "type": "http",
      "url": "https://<account-url>/api/v2/databases/METATATE_APP/schemas/CORE/mcp-servers/METATATE_MCP",
      "oauth": {
        "clientId": "<snowflake-oauth-client-id>",
        "callbackPort": 8080,
        "scopes": "session:role:<snowflake-role>"
      }
    }'

  3. Ask a Snowflake administrator to confirm the same role appears in ALLOWED_ROLES_LIST and PRE_AUTHORIZED_ROLES_LIST.

Users should not need to change their default Snowflake role to fix this.

Claude Code Plugin Commands Are Missing​

Symptom: Claude Code connects, but /metatate:* commands are not available.

Cause: The plugin is not installed, disabled, or Claude Code has not reloaded plugin metadata.

Solution:

Add the Metatate GitHub-hosted plugin repository with Claude Code's marketplace command, then install the plugin:

/plugin marketplace add metatateai/metatate-claude-plugins
/plugin install metatate@metatate-claude-plugins

Restart Claude Code if prompted. If the marketplace was already installed, update it:

/plugin marketplace update metatate-claude-plugins

Claude Code Authenticates But Tools Are Missing​

Symptom: Claude Code shows the metatate MCP server as connected, but Metatate tools are unavailable or tool calls fail immediately.

Cause: The MCP URL points to the wrong Snowflake account, app database, schema, or server name, or the server was not registered.

Solution:

Check the local registration:

claude mcp get metatate

Then ask a Snowflake administrator to verify:

SHOW MCP SERVERS IN SCHEMA METATATE_APP.CORE;

Expected server:

METATATE_MCP

Cortex Code PAT Is Invalid​

Symptom: cortex mcp start reports:

Programmatic access token is invalid.

Cause: The PAT is expired, not exported in the same shell, copied incorrectly, or not valid for the configured account.

Solution:

  1. Confirm the token variable is set:

    echo "${METATATE_CORTEX_PAT:+set}"

  2. Confirm Cortex is started from the same shell:

    export METATATE_CORTEX_PAT='<snowflake-pat-secret>'
    cortex mcp start

  3. Ask a Snowflake administrator to confirm the PAT is active:

    SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER <snowflake_user>;

Cortex Code Role Or Permission Denied​

Symptom: Cortex Code connects to MCP, but Metatate tool calls fail with role or privilege errors.

Cause: The PAT role restriction, X-Snowflake-Role header, and Metatate application role grants are not aligned.

Solution:

  1. Re-register the MCP server with the approved role:

    ./bin/metatate-cortex-mcp-add \
      --account-url https://<account-url> \
      --snowflake-role <snowflake-role> \
      --write

  2. Ask a Snowflake administrator to confirm:

    SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER <snowflake_user>;
    SHOW GRANTS TO ROLE <snowflake-role>;

  3. The PAT ROLE_RESTRICTION, X-Snowflake-Role, and role with METATATE_APP.APP_USER should all be the same intended Metatate role.

Cortex Code User Token Mismatch​

Symptom: Cortex Code account setup reports:

The user you were trying to authenticate as differs from the user tied to the access token.

Cause: The Cortex connection user in ~/.snowflake/connections.toml does not match Snowflake's canonical user name for the OAuth token.

Solution:

  1. Check the canonical user name in Snowflake:

    SELECT CURRENT_USER();

  2. Update the matching Cortex connection in:

    ~/.snowflake/connections.toml

    For example, if Snowflake returns CARLOS, use:

    user = "CARLOS"

Cortex Code Opens OAuth For Metatate MCP​

Symptom: Cortex Code opens a Snowflake OAuth browser page when connecting the Metatate MCP server.

Cause: A stale OAuth-based MCP registration exists for metatate.

Solution:

cortex mcp remove metatate
./bin/metatate-cortex-mcp-add \
  --account-url https://<account-url> \
  --snowflake-role <snowflake-role> \
  --write
cortex mcp start

The default Metatate Cortex helper writes PAT headers, not OAuth settings.

Warehouse Errors on Procedure Tools​

Symptom: authorize-use, validate-query-context, or explain-why fail with a warehouse-related error (e.g., No active warehouse).

Cause: The APP_WAREHOUSE reference is not configured or the warehouse is suspended.

Solution:

-- Check the warehouse reference
SHOW REFERENCES IN APPLICATION METATATE_APP;

-- Set or update the warehouse reference
ALTER APPLICATION METATATE_APP
  SET REFERENCES = ('APP_WAREHOUSE' = 'MY_WAREHOUSE');

-- Verify the warehouse is running
SHOW WAREHOUSES LIKE 'MY_WAREHOUSE';
ALTER WAREHOUSE MY_WAREHOUSE RESUME;

Function-based tools (discover-context, get-decision-context, inspect-data-meaning) do not require a warehouse, so if only procedures fail, the warehouse reference is the issue.

Cortex / AI Features Unavailable​

Symptom: Tools return errors related to Cortex functions, or AI-assisted features in the Metatate app do not work.

Cause: Snowflake Cortex is not available in your region, or the required database role is not granted.

Solution:

  1. Check region support: Cortex is available in select Snowflake regions. See Snowflake Cortex documentation for the supported regions list.

  2. Check the database role grant:

-- The app needs the SNOWFLAKE.CORTEX_USER database role
SHOW GRANTS TO APPLICATION METATATE_APP;

If the role is missing, grant it:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO APPLICATION METATATE_APP;
  1. Verify Cortex works directly:
SELECT SNOWFLAKE.CORTEX.COMPLETE('mistral-large', 'Say hello');

If this fails, Cortex is not available in your account or region.

Stale Governance Data​

Symptom: Tools return outdated information that does not reflect recent policy changes.

Cause: Policies were updated in the UI but not re-deployed (materialized).

Solution:

  1. Open the Metatate UI
  2. Navigate to the Deployments page
  3. Re-deploy the updated policies
  4. Verify the governance tables are updated:
SELECT MAX(UPDATED_AT) FROM METATATE_APP.CORE.GOVERNED_TABLES;

The explain-why tool also reports snapshot_status: "stale" when the governance snapshot used for a decision no longer matches current policies.

Snowflake Intelligence Says "No Agents Available"​

Symptom: Snowflake Intelligence opens, but shows No agents available.

Cause: No agent has been created yet, or your current role cannot access the agent object.

Solution:

  1. Open AI & ML -> Agents
  2. Create an agent in a writable schema
  3. Grant access to the role you use in Snowflake Intelligence
  4. Refresh Intelligence and select the agent

Snowflake Intelligence Reports a SQL Compilation Error​

Symptom: The agent tries to call a Metatate tool, then reports a SQL compilation error.

Cause: The agent was wired to a canonical core.*(VARIANT) object instead of a core.agent_* wrapper, or the wrapper parameter names do not match the expected scalar signature.

Solution:

Use the Intelligence adapter layer:

  • core.agent_discover_context
  • core.agent_get_decision_context
  • core.agent_inspect_data_meaning
  • core.agent_inspect_governance_rules
  • core.agent_authorize_use
  • core.agent_validate_query_context
  • core.agent_explain_why

Then verify:

  1. the object type is correct (function vs procedure)
  2. the parameter names match the wrapper exactly
  3. the agent was saved before starting a new chat thread

Slow Tool Responses​

Symptom: MCP tool calls take more than a few seconds to return.

Cause: Warehouse is auto-suspended or undersized for the query volume.

Solution:

  • Increase the warehouse size if evaluating many policies: 
    ALTER WAREHOUSE MY_WAREHOUSE SET WAREHOUSE_SIZE = 'MEDIUM';
  • Set a shorter auto-suspend timeout to balance cost and latency: 
    ALTER WAREHOUSE MY_WAREHOUSE SET AUTO_SUSPEND = 60;
  • Function-based tools (discover-context, get-decision-context, inspect-data-meaning) should return in under 2 seconds. If they are slow, the governance tables may be very large -- consider filtering with more specific parameters.

Getting Help​

If you encounter an issue not covered here:

  1. Check the Metatate backend logs for detailed error messages
  2. Run CALL METATATE_APP.V1.INIT(); to reinitialize the app
  3. Verify the app version and patch level: SHOW APPLICATIONS LIKE 'METATATE_APP';
  4. Contact support with the error message, your Snowflake region, and the tool name and parameters you used