Troubleshooting
Start with the failed operation and its response, then check the selected workspace, environment, and run state before retrying.
On this page
Installation and local runsAuthentication and workspace selectionDeployments, schedules, and runsConnectors, nodes, and eventsHTTP errors and availabilityInstallation and local runs
| Symptom | Likely cause and next step |
|---|---|
dagy is not found | Activate the Python environment where you installed the SDK; see installation |
| A local command calls the hosted API | dagy run switches behavior when an API URL is configured; use flow.run_local() for explicit local execution |
| Numeric or Boolean CLI parameter fails validation | --param values are strings; use typed Python arguments locally or JSON types in the run API |
run_local() does not return my flow's value | It returns the run context; inspect run status and local artifacts. Direct flow() has different execution semantics |
| Import error after deployment | The archive contains the flow source, not every local module; review packaging and dependency packages |
| Task times out but still writes data | Local timeout cannot kill a Python thread; bound the external call and make writes idempotent |
Authentication and workspace selection
| Symptom | Next step |
|---|---|
| 401 | Check the API base URL and full Bearer header, renew an expired session with dagy login, or replace a revoked API key |
| 403 | Check the effective role and the endpoint's scopes; some API keys need both granular and legacy prefix scopes |
| A key from Settings cannot deploy or trigger | The UI creates a read-only key by default; follow the writable key flow in authentication |
| A request reaches the wrong workspace | Confirm /me after setting X-Org-Id; invalid session selections can fall back to another membership |
| Login works but deploy says no API URL | Login stores credentials, not the CLI profile's API URL; explicitly configure DAGY_API_URL |
Email-only /auth/login fails | This is an authenticated token exchange; sign in or use the CLI device flow first |
Deployments, schedules, and runs
A successful POST /runs is acceptance, not workflow completion. Poll the returned run ID. If a run remains QUEUED, inspect the deployment's enabled capabilities and quota, then provide the run ID and timestamp to the service operator if it does not progress. Repeatedly submitting new runs can create duplicate work.
For FAILED or TIMED_OUT, inspect error_message, individual task states, and logs. Fix the cause before retrying. Empty logs can mean the run has not produced logs yet; a short flow-list page can still have another page. Follow the endpoint's cursor rather than inferring completion from a count.
| Symptom | Next step |
|---|---|
| Promotion runs with different packages/tier | Reapply and inspect target deployment settings; these are not all copied by promotion |
| Schedule fires at the wrong hour | Supply an explicit IANA timezone. Direct schedule API defaults differ from the SDK defaults |
| Schedule does not run repeatedly | Check enabled, next_run_at, time bounds, catchup policy, and last error; one-time/manual modes are different |
| Dependency package is not ready | Inspect package build status and logs; attach it only when ready |
| Remote logs unavailable through CLI | dagy logs and dagy runs show read local history; use the run API or console for hosted logs |
| Cancellation does not reverse a write | Cancellation stops future work where supported; it is not a destination transaction rollback |
| Retry-from-failed reruns a successful task | Prior output was not reusable or the task type cannot be reused in that runtime |
Connectors, nodes, and events
Follow the exact node's catalog entry. Check package installation, the node's supported secret reference, network access, provider resource existence, and required input ports. A saved connector or active cloud connection is not sufficient runtime credential configuration.
A TypeError mentioning safe_import and hint is a known defect in specific transform/parser nodes. Use a tested custom Python task until fixed; repeatedly changing credentials will not resolve it.
For inbound webhook errors, distinguish an invalid token (404), disabled sensor (409), unregistered flow or invalid parameters (422), and usage/rate limits. Accepted duplicate deliveries can create multiple runs. Polling without allow_concurrent can stop after its first match; see sensor limitations.
For outbound alerts, verify the supported trigger and channel configuration. The test action actually sends notifications and may evaluate other matching rules. Missing notifications do not prove a run never completed: inspect the run API and implement reconciliation.
HTTP errors and availability
A 422 usually identifies a malformed or invalid field through detail. Some feature errors return structured objects, and AI validation can return its own workflow-error envelope. Do not assume every error body has one shape. See API errors.
A capability-specific 404 or 503 can mean the feature is unavailable in your deployment. A 5xx whose message names a service configuration is an operator issue; an external developer does not need to create backend tables to resolve it. Share the sanitized response and request context with the service operator.
For rate errors, honor Retry-After when present and use bounded backoff otherwise. For quota or AI credit exhaustion, review usage and billing; short retries do not replenish an exhausted allowance.