Troubleshooting dbt connectivity

✦TL;DR

Symptom-first troubleshooting for dbt connectivity - bucket access denied, dbt Cloud access forbidden, AssumeRole failures, wrong hosts, and stale catalogs.

||

|Connect

Resolve common dbt connectivity issues when integrating dbt with Atlan. Find the symptom you're seeing in the quick index - each entry includes the check you can run yourself before opening a ticket.

Quick index

You see	Most likely cause	Jump to
AccessDenied / "Manifest file Check on Bucket check failed" (dbt Core)	Bucket policy, KMS, or explicit deny	Bucket access denied
"Access forbidden. Please check your dbt Cloud token permissions."	dbt Cloud IP restrictions (first) or token permissions (second)	Access forbidden
AccessDenied ... sts:AssumeRole	Trust policy wrong, or requires an external ID Atlan doesn't send	AssumeRole denied
"Resource not found. Please check your account/project/environment details."	Wrong host URL (usually a metadata. address)	Wrong host
"Host URL and API token are required" while rotating a token	Credential form needs both fields re-entered	Special cases § rotation
"Region not found" blocking a connection save	Core→new-experience migration field gap	Special cases § migration
Connection tests fine, but assets are missing, stale, or duplicated	Scoping / upload pipeline / docs generate	Works but wrong

Bucket access denied (dbt Core) - biggest theme

Symptom. Preflight or crawl fails with one of:

Manifest file Check on S3: failed With error code: AccessDenied - Access Denied
-- or (own role, explicit deny):
An error occurred (AccessDenied) when calling the ListObjectsV2 operation:
  ... is not authorized to perform: s3:ListBucket ...
  with an explicit deny in a resource-based policy
-- or (GCS):
[GCS] error in listing objects: googleapi: Error 403: ...
  does not have storage.objects.list access to the Google Cloud Storage bucket
-- or (new connector auth):
Access denied to the object storage location. The provided credentials ... lack
list/read permission on this bucket/container and prefix.

Check in this order:

1. Bucket name format - plain name, no s3:// prefix.
2. Permissions on the exact bucket + prefix - AWS: s3:GetObject + s3:ListBucket on both the bucket ARN and bucket/prefix/*; GCS: roles/storage.objectViewer on that bucket; ADLS: Storage Blob Data Reader.
3. KMS - encrypted bucket needs kms:Decrypt + kms:DescribeKey for the reading role.
4. Explicit denies - scan the bucket policy for "Effect": "Deny" statements; they override everything.
5. Recently changed buckets - if you moved to a new bucket, every grant must be redone for it; the old bucket's policy grants nothing.

A passing test connection isn't a passing crawl

The connectivity test validates bucket-level access only. It can pass while the crawl fails on a specific object (wrong prefix, missing manifest, KMS). If the test passes and the crawl doesn't, compare the exact prefix in your config against the bucket's real layout - then check KMS.

"Access forbidden" from dbt Cloud

Symptom. "Access forbidden. Please check your dbt Cloud token permissions." on Test Authentication - often after the token was already recreated with higher roles.

Check yourself, in this order:

1. IP restrictions first. Ask your dbt Cloud admin whether Account settings → IP restrictions is enabled. If yes: get your tenant's NAT IPs from Atlan support and allowlist them (how).
2. Then token permissions. Team plan → Read-only on all target projects; Enterprise plan → Job Viewer on all target projects (Set up dbt Cloud).
3. Test the token outside Atlan to split token vs network - replace placeholders and run:

curl -s -o /dev/null -w "HTTP status: %{http_code}\n" \
  -H "Authorization: Token <your-dbt-cloud-token>" \
  "https://<your-access-url>/api/v2/accounts/<account-id>/"
# 200 → token + host fine; the problem is between Atlan and dbt Cloud (IP restrictions)
# 401/403 → the token itself: wrong account, wrong instance, or missing permissions

AssumeRole denied (dbt Core on AWS)

Symptom.

Connection test failed: An error occurred (AccessDenied) when calling the
AssumeRole operation: User: arn:aws:sts::<atlan-account>:assumed-role/<atlan-role>/...
is not authorized to perform: sts:AssumeRole on resource:
arn:aws:iam::<your-account>:role/<your-dbt-role>

Why. Your role's trust policy doesn't accept the identity Atlan is actually using. Three causes, in order of frequency:

1. The trust policy's Principal isn't the Atlan dbt service identity ARN for your tenant (a guessed ARN, another tenant's, or a typo). Get the exact value from support and paste it verbatim.
2. The trust policy has an sts:ExternalId condition. Confirm with support whether the connector sends one before requiring it - historically it didn't, and the condition guarantees failure.
3. The role ARN entered in Atlan isn't the role that has the trust policy (two similarly named roles).

Wrong dbt Cloud host

Symptom. "Resource not found. Please check your account/project/environment details.", or auth failures on a host you expected to work.

• Use your account access URL - the address in your browser when logged into dbt Cloud: https://cloud.getdbt.com (multi-tenant) or your own like https://ab123.us1.dbt.com (single-tenant/regional).
• Any host containing metadata. is the Discovery API host - Atlan's calls don't exist there; that's the exact "Resource not found" trigger.
• Include https://; compare character-by-character. A token minted on one instance is invalid on another.

Connection works, but catalog is wrong

What you observe	Likely cause & fix
Models have no columns	dbt docs generate isn't running in the job (dbt Cloud) or catalog.json isn't uploaded (Core). Enable it; re-crawl.
Assets stopped updating weeks ago (Core)	Your upload pipeline stopped writing fresh artifacts - Atlan happily re-reads old files. Check the bucket's last-modified dates.
Duplicate-looking models	Two environments or two connections crawling the same project - scope them (Special cases).
Assets from the wrong environment	Token/credential scoped to a different dbt environment than intended. Verify account/project/environment scoping.
Workflow fails at the publish step, not extract	Not connectivity - often permissions of the workflow owner (connection admin) or a platform-side issue. Raise a ticket with the run link.

Opening ticket that gets solved fast

Include these six things - they turn a multi-day exchange into one reply:

• Your Atlan tenant URL and the failing workflow run link
• dbt flavor (Cloud or Core) and, for Core, the cloud provider and bucket name
• The exact error text from the workflow logs (paste, don't paraphrase)
• For dbt Cloud: whether IP restrictions are enabled, and the token's permission set + plan (Team/Enterprise)
• For dbt Core: the role ARN / service account used, and whether the bucket is KMS-encrypted or firewalled
• Whether it ever worked, and if so what changed around the time it stopped (new bucket? rotated token? security change?)

Other known issues

What are known limitations of dbt connector?

Following are the known limitations:

• For dbt Core, Atlan currently only processes the status of dbt tests - passed, failed, error and warning - but not the job name and execution time. However, this information is available for dbt Cloud. You can find this information in asset sidebar.
• Column-level lineage for dbt models is currently unavailable at source. However, Atlan applies a custom SQL-parsing algorithm to the materialized SQL tables to generate column-level lineage for dbt models. Note that due to the limitations of SQL parsing, Atlan doesn't guarantee generating lineage for all columns.
• Ephemeral dbt models don't materialize tables at source. Hence, these doesn't create lineage for the materialized layer or publish dbt model columns in Atlan. This is an expected behavior of ephemeral dbt models.

Does Atlan support certifiying assets, changing descriptions, owners, managing announcement, tagging assets, linking terms, readmes and Atlan domains and updating custom metadata from dbt?

Yes, you can do all these enrichmenents from dbt to Atlan. For more details, refer to the Enrich Atlan through dbt

Why are my dbt Cloud models not showing up in Atlan after setup?

Atlan only crawls dbt assets that are in the "applied" (built) state in dbt Cloud. Models must be part of a successful run to be picked up during crawling; models that are only defined in your project files but haven't been executed won't be included. For more information about project state, see Project states in dbt Cloud.

Why are columns for dbt models missing?

If you've crawled your dbt models but columns are missing:

• Define the columns in the columns attribute of the model's .yml definition in the manifest.json file.
• Check if the dbt model is materializing a table or view asset, without which columns for a dbt model don't show up.

Does Atlan support data types for dbt model columns?

Yes, Atlan supports column data types for dbt models:

• dbt Cloud: Make sure there is at least one job run with the Generate docs on run option enabled for every environment where dbt models are executed.
• dbt Core - upload the manifest.json and catalog.json files generated by the dbt docs generate command for every dbt Core project. Refer to dbt Core documentation to learn how to structure the bucket while uploading your files.

Is dbt source metadata available for materialized columns?

If metadata enrichment is enabled for assets that dbt materializes, table and column assets are updated with the materialized by dbt source, model, or seed metadata.

Can I map Atlan GitHub action to multiple dbt projects?

Yes, you can configure the Atlan GitHub action for multiple dbt projects.

Why are some dbt tests missing?

Atlan doesn't support crawling dbt tests with an auto generated unique_id that exceeds the character limit of 32,000 characters. If you want to catalog such dbt tests in Atlan, you need to define a custom name for your dbt tests within the character limit.

Why is there discrepancy in dbt test count between dbt and Atlan?

Atlan fetches dbt models, sources, and tests from the applied state of each dbt environment. This is the most recent project state for each environment. The asset count on Atlan may differ from what's present in the manifest files for individual job runs. Refer to dbt documentation to learn more about dbt project states.

Why is enriched metadata from dbt not appearing on my materialized assets?

If metadata enriched through dbt (tags, terms, domains, and more) isn't appearing on your materialized assets, check the following:

1. Go to your dbt workflow and open the Config tab.
2. Verify that the Connection field points to the correct data warehouse connection (for example, Snowflake, BigQuery, Redshift, and more).
   If this field is left empty, the workflow searches for materialized assets across all connections in your Atlan instance.
3. Make sure that only one dbt connection is enriching the same data warehouse connection. Multiple dbt connections enriching the same connection can lead to metadata conflicts and unexpected results.

Why does Atlan link dbt model description to my SQL source table?

If a materialized table is linked to multiple dbt assets, Atlan applies the description from the linked dbt model to the materialized asset. In case this is unavailable, Atlan then applies the description from the linked dbt source to the asset.

Why does Atlan link dbt seed description to my SQL source table?

If a materialized table is linked to multiple dbt assets, Atlan applies the description from the linked dbt seed to the materialized asset. In case this is unavailable, there is no description available.

Does Atlan work with dbt Cloud single-tenant and multi-tenant deployments?

Yes. Atlan integrates with all dbt Cloud deployment options using the same two APIs regardless of tenancy model:

• dbt Cloud Administrative API—fetches account, project, environment, job, and run metadata
• dbt Cloud Discovery API—fetches models, sources, and tests from each dbt environment

See Set up dbt Cloud for configuration details.

Why is "View in dbt" link missing for some assets?

Atlan displays the View in dbt link only for assets that have a target URL—meaning they were created or synced after the dbt connector was set up. The link appears for models, sources, and tests. Assets without a target URL (typically older assets synced before the connector was configured) won't show the link.