Troubleshooting

Troubleshooting

This page covers common issues you may encounter when using Orquestio, along with diagnostic steps and solutions.

---

Instance stuck in provisioning state

Symptoms: Your instance status remains provisioning for more than 10 minutes after creation.

Possible causes:

• AWS capacity constraints in the target region
• A transient error during Terraform apply

What to do:

1. Check instance status via GET /instances/{id}.
2. If the state has not changed after 15 minutes, contact support with your instance ID.
3. Do not attempt to create a second instance for the same tenant — the orchestrator will reject it.

Caution

Do not repeatedly call POST /instances while a provisioning operation is in progress. The orchestrator enforces one active operation per instance.

---

401 Unauthorized errors

Symptoms: API calls return 401 Unauthorized.

Possible causes:

• Missing or malformed Authorization header
• Expired or revoked token

What to do:

1. Verify your request includes the header: Authorization: Bearer <your-token>
2. Confirm the token is still valid in the customer portal.
3. Generate a new token if needed and retry.

---

403 Forbidden when accessing your instance

Symptoms: Requests to your instance’s IP address return 403 Forbidden.

Cause: All Orquestio instances are configured to reject direct IP access. Traffic must flow through Cloudflare.

What to do:

• Always access your instance via its assigned *.orquestio.com subdomain or your configured custom domain.
• Never use the raw Elastic IP in a browser or API client.

Tip

If you see 403 on what looks like a valid domain, verify that your DNS is resolving through Cloudflare and not directly to the instance IP. Run nslookup yourdomain.com to confirm.

---

429 Too Many Requests

Symptoms: API calls return 429 with a rate limit message.

Cause: You have exceeded the per-endpoint rate limit (10-60 requests/minute depending on the endpoint).

What to do:

1. Implement exponential backoff in your client.
2. Check the Retry-After header in the response for the recommended wait time.
3. If your workload legitimately requires higher throughput, contact support to discuss limit adjustments.

---

Custom domain not working

Symptoms: Your custom domain returns a DNS error, connection timeout, or certificate warning.

Possible causes:

• CNAME record not created or not yet propagated
• TLS certificate still pending issuance

What to do:

1. Verify your CNAME record points to the endpoint returned by POST /instances/{id}/custom-domain.
2. Check DNS propagation: nslookup yourcustomdomain.com
3. Certificate provisioning via Let’s Encrypt can take up to 5 minutes after CNAME verification. Wait and retry.
4. If the certificate still shows as pending after 15 minutes, check that no CAA DNS record is blocking Let’s Encrypt issuance on your domain.

---

Instance health check returning unreachable

Symptoms: GET /instances/{id} reports health status as unreachable.

Possible causes:

• The EC2 instance is stopped or in a failed state
• The Docker container inside the instance has crashed
• A security group or networking misconfiguration (rare, managed by Orquestio)

What to do:

1. Check if you recently triggered a resize or other operation — the instance may be restarting.
2. Wait 2-3 minutes and re-check status.
3. If the instance remains unreachable, contact support. Orquestio ops can inspect the instance via SSM.

---

Task dispatch returning 409 Conflict

Symptoms: An API call to dispatch a task or modify an instance returns 409 Conflict.

Cause: Another operation (provisioning, resizing, domain configuration) is already in progress on this instance. The orchestrator enforces serial execution of state-changing operations.

What to do:

1. Poll GET /instances/{id} until the current operation completes.
2. Retry your request once the instance returns to a stable state (running, stopped).

Caution

Do not attempt to force concurrent operations. The 409 response is a safeguard against race conditions that could leave your instance in an inconsistent state.

---

Cannot access instance after resize

Symptoms: Your instance becomes temporarily unreachable after a resize operation.

Cause: Instance resizing requires stopping and restarting the EC2 instance, which involves a brief period of downtime. The Elastic IP remains the same, but the instance and container need time to come back up.

What to do:

1. Wait 3-5 minutes after the resize operation completes.
2. Check status via GET /instances/{id} — it should transition back to running.
3. If the instance does not recover within 10 minutes, contact support.

---

OpenClaw UI not loading

Symptoms: You can reach your instance’s domain but the OpenClaw web interface shows a blank page, connection refused, or gateway error.

Possible causes:

• The OpenClaw Docker container has not started yet (common immediately after provisioning)
• Port mapping misconfiguration
• The container crashed due to missing or invalid environment variables (e.g., LLM API key)

What to do:

1. Wait 2 minutes after provisioning — the container may still be pulling its image and starting.
2. Verify your instance status is running via the API.
3. Check that required environment variables (especially LLM API keys) are set correctly in the customer portal.
4. If the issue persists, contact support for container-level diagnostics.

---

Checking orchestrator health

If you suspect a platform-wide issue rather than a problem with your specific instance, check the orchestrator’s health endpoint:

GET https://api.orquestio.com/health

A healthy response returns 200 OK. If this endpoint is down or returning errors, the issue is on Orquestio’s side — check the status page or contact support.