Troubleshoot a deployed model

Troubleshoot deployment and model-management issues, from missing outputs and Snowflake configuration or privilege errors to pull and teardown failures.

Troubleshoot

Start with rai doctor for configuration and connection diagnostics, then find the symptom below that best matches what you’re seeing.

rai doctor

If the issue still looks configuration-related, also run:

rai config explain

When you need a deeper look or want to share diagnostics with RelationalAI support, generate a doctor report. It bundles the resolved configuration, connection and privilege checks, deployment state, and recent run traces into a single zip:

rai doctor report

This writes doctor_report_<timestamp>.zip to the current directory. Attach that zip to your support request. See rai doctor report for command details and options.

If you deploy programmatically by building a config in Python and passing it to Model(config=...) rather than using a raiconfig.yaml file, run the report from Python and pass the same config, so it reports on the configuration your deployment actually used:

from relationalai.tools.cli.doctor_report import run_doctor_report

run_doctor_report(config=config)

Inside a Snowflake Notebook, use download_doctor_report instead. It generates the report and renders a button to download the zip:

from relationalai.tools.cli.doctor_report import download_doctor_report

download_doctor_report(config=config)

No objects show up in the target schema

If rai models deploy succeeds but the target schema still looks empty, you’re most likely looking at a different schema than the one the model deployed to. Verify that deployment.public_schema is correct and that you’re using the expected profile.

Deployment cannot resolve a database

If neither the active Snowflake connection’s database nor the deployment.public_schema configuration option supplies a database, deployment reports a configuration error instead of selecting a placeholder database. Set deployment.public_schema to a fully qualified DATABASE.SCHEMA value, or set database on the active Snowflake connection in raiconfig.yaml. An unset connection database is fine when deployment.public_schema includes a database.

Deployment reports that an object does not exist or is not authorized

Snowflake uses this message both for an object that doesn’t exist and for one the role can’t access. PyRel deploys with secondary roles turned off, so you also see this message when your access to the object comes only from a secondary role. Check the object name first. If the name is correct, confirm whether the deployment role can access the object without secondary roles by running the following:

USE ROLE <deployment_role>;
USE SECONDARY ROLES NONE;
DESCRIBE TABLE <database>.<schema>.<table>;

If DESCRIBE TABLE fails with the same message, have your Snowflake administrator grant the privilege to the deployment role, then run rai models deploy again.

Snowflake raises a privilege error during model refresh

If deployment succeeds but the model refresh task fails with a privilege error, the deployment.role you configured most likely does not have permission to execute Snowflake tasks. Confirm the target schema and access configuration with your Snowflake admin or with RelationalAI support.

Source tables are not visible in the target schema

Only model outputs are deployed into the target schema. Source tables stay in their original schemas and aren’t affected by deployment. Check your tables configuration to confirm which schema your source tables come from.

Unexpected objects show up in the target schema

The public schema holds one view per output. Everything else PyRel creates goes in the internal schema, including the objects that store the outputs’ data, which are named with an _INTERNAL_STORE_ prefix.

The compiler chooses how to store each output: a table, a dynamic table, or nothing stored at all. You can override that in raiconfig.yaml with deployment.materialized and deployment.incremental, or per output in deployment.overrides. Both default to auto, which leaves the choice to the compiler. If an expected dynamic table is missing, check whether PyRel used a plain table because the output cannot be backed by one. Note that an override naming an internal object matches nothing, because overrides address outputs by their public names.

A graph algorithm result does not appear in the public schema

Your model calls a graph algorithm, rai models deploy succeeds, but the concept view has no column for the result and no view carries its name. PyRel computed the result and stored it in the internal schema, as an object with the _INTERNAL_STORE_ prefix, because nothing in the model exposes it. A result becomes part of a public output only when you attach it to the node concept or use it in a definition.

Expose the result as shown in Expose algorithm results as outputs, run rai models deploy again, and wait for the refresh. Then query the column or view:

SELECT ID, PAGERANK
FROM MY_DATABASE.MY_MODEL.ACCOUNT
LIMIT 10;

A populated column confirms that the result is exposed and refreshed. A column that exists but is empty means the refresh hasn’t finished. Check it with REFRESH_STATUS() as described in Monitor a deployed model.

A refresh that runs graph algorithms is slow or stays in RUNNING

REFRESH_STATUS() reports RUNNING for longer than you expect, most often on the first refresh after you add a graph algorithm to the model. Some algorithms run on the logic reasoner rather than in SQL. See Which graph algorithms use the logic reasoner. The first refresh that needs the reasoner creates or resumes it, which can take a few minutes, and later refreshes queue a job on it.

Check the reasoner’s status. Replace my_reasoner with the name set by reasoners.logic.name, or with your Snowflake username with dots replaced by underscores when no name is set:

CALL relationalai.api.get_reasoner('logic', 'my_reasoner');

If STATUS isn’t READY, the reasoner is still starting. Wait and check again. If it’s READY but the refresh is still running, check whether the refresh job is queued behind other work with View all jobs.

If the same refresh is slow every time, check how the result is exposed. Attaching a result that runs on the logic reasoner as a property of a concept currently makes the whole concept, with all of its attached properties, compute on the logic reasoner. Moving that result into a standalone relationship with a definition can improve performance. See Expose algorithm results as outputs for the definition form.

If the refresh is still slow, the reasoner may be too small for the graph or shared with too much other work. Configure a larger size with reasoners.logic.size, or see Scale reasoner capacity. If none of this explains the delay, generate a doctor report with rai doctor report and attach it to your support request.

A deploy is refused because the remote has changes

Someone else or another session deployed since your last pull, so the remote is ahead of you. If the changes are shared deployment state, run rai models pull to reconcile them, then run rai models deploy again. If rai models pull reports code-owned changes, those changes live in a collaborator’s source files, so reconcile them through version control with git pull first, then pull and deploy. Pass --path so PyRel can verify that your source is in sync.

`rai models pull` won’t overwrite `shared_model.py`

Pull protects a locally edited shared_model.py from being overwritten. Re-run rai models pull --force. PyRel backs up your current file to shared_model.py.<timestamp>.bak first.