Skip to main content

Troubleshooting

This page covers common issues you may encounter when using Metatate's canonical MCP layer or the supported Snowflake Intelligence wrapper workflow.

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.

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-powered features (like natural language policy evaluation in authorize-use) do not work.

Cause: Snowflake Cortex is not available in your region, or the required privilege 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 privileges:

-- The app needs IMPORTED PRIVILEGES on the SNOWFLAKE database
SHOW GRANTS TO APPLICATION METATATE_APP;

If the privilege is missing, grant it:

GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE 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_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