Help
Troubleshooting
Start with the persisted workflow diagnostic, admission reason, job conclusion, attempt, and audit event. Rerunning without identifying that first failure usually removes useful context without changing the outcome.
Collect a safe evidence bundle
Record identifiers and immutable metadata before changing source, credentials, environment rules, or billing controls.
- 1
Identify the tenant and source
Organization name/ID, repository full name/provider, workflow path/ID, run ID/number, source SHA/ref, trigger, and provider delivery ID when available. - 2
Locate the first failing object
Job ID/key, attempt number, step name/position, status, conclusion, exit code, timestamps, and workflow diagnostic code/path. - 3
Capture bounded output
Download the masked job log or use the smallest MCP tail that includes the first error. Include artifact name/digest, not artifact contents unless required. - 4
Check policy and capacity
Environment decision/wait/ref rule, concurrency group, plan concurrency, usage reservation, subscription status, and spend control. - 5
Preserve relevant audit events
Record provider, configuration, approval, MCP, billing, or integration actions around the incident window.
Never paste credentials into support evidence
Do not include decrypted secrets, repository tokens, relay bearer values, Slack webhooks, MCP credentials, raw environment blocks, or unmasked logs. Prefixes, IDs, hashes, timestamps, and sanitized provider error codes are sufficient for correlation.
Workflow compatibility diagnostic codes
The code family points to the parser or resolver that rejected migration or activation. The diagnostic message and path contain the concrete value to fix.
| Code family | Meaning | Typical fix |
|---|---|---|
workflow.yaml / workflow.conversion | YAML parse or Actions template conversion failed. | Fix YAML shape/types at the reported path; quote ambiguous values. |
workflow.path | File is outside .runnable/workflows or has the wrong extension. | Move to .runnable/workflows/name.yml or .yaml. |
workflow.trigger / unsupported.event.* | No supported trigger or an unsupported event was requested. | Use a documented trigger or split provider-specific automation. |
workflow.jobs / workflow.job / workflow.steps | Job or step shape is missing/invalid. | Provide a mapping, runs-on, and run/uses steps. |
workflow.unknown_need / workflow.job_cycle | Dependency ID does not exist or the DAG contains a cycle. | Correct job keys and make needs acyclic. |
unsupported.runner | Runner label does not resolve to supported Linux x64 configuration. | Use Ubuntu 22.04/24.04 or a supported 2–32 vCPU Linux label. |
unsupported.timeout | Job timeout is outside the 1–360 minute contract. | Choose an integer from 1 through 360. |
workflow.matrix / workflow.strategy | Matrix shape, include/exclude, fail-fast, or max-parallel is invalid. | Fix the reported strategy path and evaluate JSON output shape. |
unsupported.dynamic_reusable_matrix | Dynamic matrix is attached to a reusable-workflow caller. | Expand before the call or move the dynamic matrix into ordinary jobs. |
workflow.reusable_* | Called workflow missing/unresolvable, cycle, or input/secret mismatch. | Resolve the exact trusted ref and align workflow_call declarations. |
workflow.permissions / OIDC 409 | Invalid scope/access or OIDC signing is not configured. | Use supported permission scopes and configure the stable OIDC signing key before requesting id-token: write. |
workflow.services | A service image, credential, port, volume, or option is invalid. | Use Actions service syntax; keep bind mounts inside GITHUB_WORKSPACE and let Runnable own the service network. |
unsupported.job_container | Native job-container syntax is not supported. | Run on the Linux host runner and use services, Compose, docker run, or Testcontainers for dependencies. |
action.runtime-dependent | Paste scan lacks repository/action runtime evidence. | Run repository-backed scan so action.yml and nested actions can resolve. |
action.unsupported | Resolved action cannot preserve supported semantics. | Use a supported major/input/runtime or replace the action. |
Checkout failures
Use the checkout step annotation to separate provider authorization from workflow input and source-coordinate problems.
| Symptom | Check | Recovery |
|---|---|---|
| Repository/ref not found | Repository still selected in the GitHub installation; ref/SHA exists and is reachable. | Restore selection or dispatch a valid trusted ref. |
| Resource not accessible by integration | Requested workflow permission and GitHub App grant. | Grant the needed fine-grained permission or narrow workflow permissions. |
| Fork PR cannot write | Expected fork safety downgrade. | Move privileged work to a trusted branch/manual workflow; do not override safety. |
| SSH/custom server/filter rejected | Native checkout intentionally rejects unsupported auth/server/partial clone inputs. | Use HTTPS GitHub.com and supported checkout inputs. |
| Entire mirror URL mismatch | URL must be entire://cluster/gh/owner/repo and match GitHub identity. | Correct coordinates and save checkout settings again. |
| Entire authentication | Repository-scoped ENTIRE_TOKEN exists, is current, and can read the coordinates. | Replace the token, test checkout, then revoke the old token. |
| LFS or submodule failure | Token can access every private nested repository and requested LFS object. | Grant provider access or change checkout configuration. |
Blocked deployments
A protected job remains queued until every gate passes; a rejected approval is terminal for that job.
| Gate | What to inspect | Action |
|---|---|---|
| Wait timer | Requested time, configured minutes, durable job state. | Wait; redeploying restarts the protected request. |
| Required reviewer | Selected member IDs and pending decision. | Ask an eligible current member to approve or reject. |
| Self-review | Triggering actor equals proposed reviewer. | Use another configured reviewer. |
| Admin bypass | preventAdminBypass and the explicit bypass flag. | Follow policy; do not treat owner role as automatic bypass. |
| Branch/tag policy | Actual source ref versus all/protected/selected patterns. | Dispatch an allowed ref or update the rule before a fresh run. |
| Environment missing | Job environment name resolves case-insensitively in this repository. | Create/fix the repository environment and rerun. |
| Billing/concurrency | Admission reason may be commercial/capacity rather than environment. | Resolve the plan gate; protection will then continue. |
Missing, partial, or stalled logs
Distinguish a display/transport issue from an execution failure and from retention expiry.
- 1
Refresh the current attempt
A rerun or automatic infrastructure retry changes the job’s current attempt. Make sure you are not looking at an older attempt. - 2
Use the download endpoint
Try the full text download or an HTTP byte range. The live browser stream can disconnect while stored chunks remain available. - 3
Check heartbeat and conclusion
An abrupt end plusinfrastructure_failureindicates startup/provider/heartbeat reconciliation, not necessarily application output. - 4
Check retention
Expired log chunks are filtered before object access. Plan retention is frozen when the log is created. - 5
Correlate annotations
Step exit code, workflow commands, problem matchers, and summary can retain useful structured evidence even when the final line is absent.
MCP returns a tail, not a complete log
get_job_logs is bounded by both lines and bytes. If truncated is true, request a larger bounded tail or use the authenticated customer download.Billing and dispatch rejection
The job is blocked before runner provisioning, so repeatedly dispatching cannot consume its way through the gate.
| Message | Cause | Recovery |
|---|---|---|
| An active trial or subscription is required | Subscription is incomplete, past_due, cancelled, or missing. | Complete checkout or resolve payment in the Stripe customer portal. |
| Plan concurrency limit reached | Active jobs equal the plan maximum. | Wait/cancel obsolete work or upgrade capacity. |
| Included-minute allowance would be exceeded | Stop-at-allowance plus completed/reserved/requested usage exceeds included minutes. | Wait for period reset, enable metered overage, or change plan. |
| Monthly hard spend cap would be exceeded | Projected base + overage including worst-case reservations exceeds cap. | Owner raises/removes the cap or reduces runner size/timeout. |
| Hard cap cannot be lower than base price | Invalid owner control. | Choose an amount at least the plan base price. |
| Budget alert must be greater than base price | Alert threshold cannot fire meaningfully below fixed base. | Choose a higher alert or leave it unset. |
Budget alerts are not spend caps
A triggered alert is an audit and billing signal. It does not stop dispatch unless stop-at-allowance or a hard cap also blocks it.
MCP connection and tool failures
Separate pre-tool HTTP authentication from a valid MCP tool result with isError.
| Failure | Action |
|---|---|
| 401 bearer error | Verify the complete rnmcp_ token is in Authorization, is not expired/revoked, and the client reloaded its secret. |
| 403 subscription required | Confirm an active or trialing Runnable plan in the token’s organization. |
| Origin/host rejection | Use the canonical production URL; deployment operators can explicitly allow trusted client origins. |
| Operator tool missing | The token is read-only. Do not replace it with operator access unless mutation is required and approved. |
| Run/job/workflow not found | List the object with the same token. IDs from another organization are intentionally invisible. |
| wait timedOut | Normal bounded long-poll expiry, not a run timeout. Repeat with the returned cursor. |
Incident and support escalation
Escalate after collecting the safe evidence bundle, or immediately for suspected tenant isolation, credential exposure, billing corruption, or widespread infrastructure failure.
| Scope | Where to check |
|---|---|
| Runnable product or billing | Contact the Runnable team |
| GitHub event/token/check incident | GitHub Status |
| Vercel control plane or sandbox incident | Vercel Status |
| Stripe checkout, portal, or invoice incident | Stripe Status |
| Slack delivery incident | Slack Status |
Runnable status disclosure
Check the public Runnable status page for the latest completed canary and its 14-day incident history. Use the support contact for product-wide incident confirmation and include affected organization/run IDs plus the incident time window.