Signing in and access
| Symptom | Likely cause | Where to look |
|---|---|---|
| ”Your session expired. Sign in to pick up where you left off.” | Not a failed sign-in, your previous session timed out | Sign in to your tenant |
| ”Your account has no access yet. Ask an administrator for an invitation.” | You signed in, usually via SSO, with an email that has no membership in any tenant | Sign in to your tenant |
| A wrong-password or wrong-email error | The password form rejected your credentials, often a typo in the email | Sign in to your tenant |
| An invitee signs in with SSO before opening their invitation link and lands on a new-tenant setup flow | Dippr doesn’t yet recognize them as the person you invited; the invitation stays pending and opening the invitation link later joins them to your tenant correctly | Invite a user |
Integrations and connections
| Symptom | Likely cause | Where to look |
|---|---|---|
| A PostgreSQL or ClickHouse connection fails to reach the database | Reachability, credentials, or the target database name; the driver’s message is passed through unedited | PostgreSQL integration, ClickHouse integration |
| A Snowflake connection fails to authenticate, or a query fails for lack of a running warehouse | The account, user or role is wrong, or the named warehouse doesn’t exist or can’t be used | Snowflake integration |
| A Google Sheets integration reports a credential or permission error | The metadata spreadsheet, or a sheet it names, isn’t shared with the service account | Google Sheets integration |
A Jira Cloud catalog fails with the API rejected the catalog's credentials or the credential check failed, or an engine refuses the catalog | The email or API token is wrong or revoked, the site name is wrong, or the engine is older than the Jira Cloud kind and needs its pending platform update | Jira Cloud integration, Catalogs and apply |
| A DuckDB source’s URI is refused, or fails to attach | The URI’s cloud credential is missing or set where it shouldn’t be, or the URI contains a character that can’t be used in a query | DuckDB integration |
| An Iceberg REST catalog answers with an authentication error, or rejects your warehouse name | The OAuth credentials or token endpoint are wrong, or the named warehouse doesn’t exist on that catalog | Iceberg REST catalog integration |
A cloud credential is refused at save, or sts:GetCallerIdentity is denied | A field required for the chosen auth method was left empty or set incorrectly, or your organization’s cloud policy blocks the role | Cloud credentials |
| An SSH tunnel won’t connect, or a tunnelled Postgres source fails its TLS check | The bastion’s host key changed, TCP forwarding isn’t allowed for the tunnel user, or SSL mode is set to verify-full instead of require | SSH tunnels |
Data planes
| Symptom | Likely cause | Where to look |
|---|---|---|
| A data plane you deployed still reads Disconnected | The deployment isn’t actually running, holds another plane’s registration secrets, or holds a credential you’ve since rotated out | Reading data plane status |
| A freshly registered plane shows Disconnected | Expected: it stays that way until you deploy it with the credentials shown at registration and it connects | Reading data plane status |
Query engines
| Symptom | Likely cause | Where to look |
|---|---|---|
| Creating an engine is refused | The name is already taken, the size isn’t available on your plan, or a configuration value is out of its valid range | Create an engine |
| Engine sign-in redirects, then fails with an audience or issuer mismatch | Your client is pointed at the wrong engine URL, copied from a different tenant or plane | Engine sign-in and OAuth |
| Sign-in works but every query is refused | A row or column-level grant issue, not an authentication problem | Engine sign-in and OAuth |
| A service user’s token mint is refused, naming a missing capability | The API key wasn’t minted with the scope the token needs; scopes are fixed at mint time, so a new key is required | Engine sign-in and OAuth |
| A hand-rolled client dies mid-query with no error until the session is already gone | It doesn’t handle the coordinator’s token-refresh challenge on a running query’s poll | Connect to an engine |
Search and Explore
| Symptom | Likely cause | Where to look |
|---|---|---|
| Search shows an empty state instead of results | Your organization has never been crawled | Metadata search |
| Search seems to be missing recent changes, or a crawl seems to run forever | Check dip crawl status; an empty result and an index that was never built look identical from the console alone | Configure search indexing |
Semantic layer
| Symptom | Likely cause | Where to look |
|---|---|---|
| Verifying a question fails, naming something broken | A metric or model the question depends on was renamed or deprecated since it was saved | Questions and review |
AI agents and MCP
| Symptom | Likely cause | Where to look |
|---|---|---|
| Every call answers 401 in your coding agent | The authenticate step never ran, or your session expired | Connect an AI agent |
| A tool call succeeds but returns nothing you expected | Check for an access-denied response before assuming something’s broken; your roles may not reach that data | Connect an AI agent |
| Search or semantic-layer tools are missing from the tool list | Your tenant’s plan doesn’t include that feature yet | Connect an AI agent |
| A connection is missing tools that a newly enabled feature should add | Scopes are fixed at the moment you approve a connection; disconnect and reconnect to pick up the wider set | Connect an AI agent |
A file tool (file_list, file_upload_url, file_download_url, file_delete) is refused with missing_scope | The tools are listed but a standard OAuth connection cannot use them; use dip file list and the other dip file commands in a terminal instead; dip asks you to approve once in the browser if it needs to. For an API-key connection missing a file permission, use a workspace API key minted with that permission | Upload and download files |
| A “several engines” error from a tool call | Name one explicitly with the tool’s engine argument; there’s no default once your tenant has more than one | Connect an AI agent |
Data apps
| Symptom | Likely cause | Where to look |
|---|---|---|
| ”This app is not installed yet” | No one has installed it for your tenant | Use an installed app |
| ”This app failed to install” | Something went wrong provisioning it; a Data admin can see the reason and retry | Use an installed app |
| ”This app was parked by an administrator” | It won’t wake on its own; only a Data admin’s Wake action restarts it | Use an installed app |
dip app push refuses before building, naming a role | Your key’s service user doesn’t hold the Data engineer role | Build and push an image |
| A push succeeds but the app never appears, or appears with an error | The image had no manifest label, or the label didn’t parse; check Recent pushes for the exact reason | Build and push an image |
docker login succeeds, but docker push is refused | Your service user doesn’t hold the Data engineer role | Manage the app registry |
dip app push or dip pipeline push stops because docker login did not finish within 1m30s | A Docker credential helper is waiting on your keychain or on a prompt nobody can see | Manage the app registry |
| ”Too many requests” on a push | You’ve hit the tag or repository quota for your tenant on that plane | Manage the app registry |
The dip CLI
| Symptom | Likely cause | Where to look |
|---|---|---|
A dip doctor row shows FAILED | The requirement is present but broken, such as a stopped Docker daemon or a Python version below the floor | Install dip and sign in |
”Docker is installed but not running. Start Docker Desktop, then run this command again.” from dip app build, dip app push, dip app check or dip doctor | Docker is on your machine but its engine isn’t answering; on Linux the message says to start the Docker service | Start Docker, wait until it reports running, then run the command again. Set DIP_VERBOSE=1 to see Docker’s own error. |
dip app push refuses immediately with “this credential may pull but not push” | The service user’s key lacks the app-publishing scope, or the user lacks the Data engineer role | Using dip in CI |
dip app push with your own login says “publishing an app needs the Data engineer role” | Your role doesn’t include publishing apps; ask a Data admin to grant you the Data engineer role, or ask a data engineer to publish the app | Roles and permissions matrix |
docker: command not found, or a build or push step hangs in CI | Docker is missing, or its daemon isn’t running on the runner | Using dip in CI |
| A multi-platform push fails with “exec format error” | The runner can’t build the non-native architecture and QEMU emulation isn’t set up | Using dip in CI |
dip app push fails, naming a tenant field it expected | The tenant publishes no registry endpoints at all; set --registry explicitly | Using dip in CI |
dip pipeline list says your sign-in does not carry pipelines:read | The sign-in was made before pipelines joined the default sign-in; run the dip login command the message prints | dip commands |
A dip pipeline command says pipelines are not available in this workspace | The workspace’s deployment does not include pipelines; no new sign-in or API key adds them | dip commands |
Related
Reading data plane status
What Connected and Disconnected mean, and what to check when a plane won’t come up.
Connect an AI agent
Connect Claude, Codex or Cursor to your tenant, and what to do when a call fails.