Troubleshooting

This page covers specific errors you may encounter while using Rills, organized by where the problem occurs. For general questions about how Rills works, see the Help Center.

Workflow failures

When a workflow execution fails, Rills records the error and marks the run as failed in your execution history. If you have the Workflow Failures notification enabled (Settings > Notifications), you will receive an alert.

To diagnose a failure:

1. Open the workflow and go to the execution history tab.
2. Find the failed run -- it is marked with a red status indicator.
3. Expand the run to see which step failed and the error message.

Common causes:

• Missing configuration -- a node references a field or variable that has not been set. Check the node config panel for empty required fields.
• Disconnected integration -- the workflow uses an integration whose OAuth token has expired or been revoked. See Integration disconnections below.
• Invalid input data -- the trigger payload or a previous step's output does not match what the next step expects. Check the step input/output data in the execution detail view.
• Timeout -- the workflow or an individual step exceeded its time limit. Long-running custom code is the most common cause.

Custom code errors

Custom code runs in an isolated sandbox. When execution fails, the error includes one of four codes:

OOM_KILLED (exit code 137)

Your code exceeded the sandbox memory limit. The process was killed by the operating system.

Fix: Reduce the amount of data loaded into memory. Avoid reading entire large files or datasets at once -- process data in chunks or filter before loading. If you are working with large JSON payloads, extract only the fields you need.

TIMEOUT (exit code 143)

Execution exceeded the configured timeout. The maximum allowed timeout is 300 seconds (5 minutes).

Fix: Increase the timeout in the custom code node configuration if you have headroom below the 300-second maximum. If your code genuinely needs more than 5 minutes, break it into multiple steps or optimize the slow operation (inefficient loops, unnecessary network calls, unindexed data processing).

EXECUTION_FAILED

Your code threw an unhandled exception or exited with a non-zero exit code (other than 137 or 143).

Fix: Check the stdout and stderr output in the execution detail view. The error message and stack trace are captured there. Common causes: undefined variables, missing imports, JSON parse errors, type mismatches. Add try/catch blocks around risky operations to surface better error messages.

SANDBOX_ERROR

An infrastructure-level failure occurred -- the sandbox itself failed to start or communicate. This is not caused by your code.

Fix: Retry the execution. If the error persists across multiple retries, contact support with the execution ID.

Webhook issues

Webhooks return HTTP status codes that indicate what went wrong:

400 -- Invalid request

The webhook URL is malformed, the request body is not valid JSON, or the short ID format is invalid.

Fix: Verify the webhook URL is correct and the request body is valid JSON. If sending from an external service, check that the content type header is set to application/json.

401 -- Unauthorized

Authentication failed. Either the API key does not match or the HMAC signature is invalid.

Fix: For API key authentication, verify the header name and value match what is configured in the webhook settings. For HMAC signatures, check that the signing secret and algorithm match. Regenerate the webhook secret if needed.

404 -- Not found

No webhook exists with the given short ID.

Fix: Check the webhook URL for typos. If you recently deleted and recreated the workflow, the webhook URL may have changed. Copy the current URL from the workflow's trigger configuration.

410 -- Gone

The webhook has already been used (for one-time webhooks) or has expired.

Fix: One-time webhooks can only fire once. If you need to receive another request, create a new webhook or switch to a persistent webhook type. For expired webhooks, check the expiry settings in the workflow trigger configuration.

429 -- Rate limited

Too many requests in a short period. The response includes a Retry-After header.

Fix: Back off and retry after the indicated period (typically 60 seconds). If you are sending bulk requests, add delays between them. If you consistently hit rate limits, contact support about higher limits.

503 -- Disabled

The webhook endpoint is disabled.

Fix: Re-enable the webhook in the workflow's trigger settings. Webhooks are automatically disabled when a workflow is archived or paused.

Integration disconnections

When an OAuth token expires or is revoked by the external service, all workflows using that integration will fail until you reconnect.

Signs of a disconnected integration:

• Workflow failures with "unauthorized" or "token expired" errors
• Integration shows a warning indicator in Settings > Integrations

To reconnect:

1. Go to Settings > Integrations.
2. Find the disconnected integration and click Disconnect.
3. Click Connect to re-authorize with the external service.
4. Re-run any failed workflows that depend on this integration.

Some services revoke tokens after a period of inactivity, after password changes, or when you remove the app from the service's authorized applications list.

Credit and billing issues

Running out of credits

Rills has two credit types: Workflow Credits (for external API calls, custom code, file operations) and AI Credits (for AI model calls). When either quota is exhausted and your spending cap is reached, workflows that would consume additional credits pause.

To check your current usage: go to Settings > Billing and review the usage section.

Options when credits run out:

• Wait -- credits reset at the start of your next billing cycle.
• Raise spending cap -- allows overage billing at your plan's per-unit rate. See Billing & Credits for overage rates.
• Upgrade your plan -- higher plans include more credits and lower overage rates.

Spending cap reached

The default spending cap is 50% of your subscription price. When reached, credit-consuming operations pause. Adjust the cap in Settings > Billing.

Unexpected credit usage

If usage is higher than expected, check for:

• Scheduled workflows with frequent trigger checks (each check costs Workflow Credits even when the workflow does not proceed)
• AI nodes processing large payloads (more tokens = more AI Credits)
• Retry loops on failing steps that repeatedly consume credits

See Billing & Credits for a full breakdown of what costs credits and what is free.

Getting help

• Help Center -- visit /help for general product questions, getting started guides, and feature explanations.
• Support -- email support@rills.ai with your workspace name and any relevant execution IDs. Include the error message and the steps you have already tried.