Troubleshooting Guide

Common issues and solutions when working with Jetty.

Authentication Errors

Error: "Invalid or expired token"

Cause: API token is incorrect or has expired.

Solution:

1. Generate a new token from the Jetty dashboard
2. Verify token format: mlc_xxxxxxxxxxxxxxxxxxxxxxxx
3. Check token is correctly set:

echo $JETTY_API_TOKEN
# Should output: mlc_xxxxxxxx...

Error: "Access denied to collection"

Cause: Token doesn't have permission for the collection.

Solution:

• Verify you're using the correct collection name in the URL
• Check your organization membership
• Contact collection owner for access

---

Workflow Execution Errors

Error: "Activity not found: xxx"

Cause: Invalid activity name in step configuration.

Solution:

1. Check spelling of activity name
2. Verify against Step Library
3. Use exact activity names:

// Correct
"activity": "litellm_chat"

// Wrong
"activity": "litellm-chat"
"activity": "LiteLLM_Chat"

Error: "Path expression failed: xxx"

Cause: Referenced path doesn't exist in trajectory.

Solution:

1. Check step execution order - referenced step must run first
2. Verify output field name matches exactly
3. Debug with trajectory inspection:

curl "https://flows-api.jetty.io/api/v1/db/trajectory/collection/task/traj_id" \
  -H "Authorization: Bearer $JETTY_API_TOKEN" | jq '.steps'

Workflow Timeout

Cause: Execution exceeded timeout limit.

Solution:

1. Check logs for slow steps
2. Reduce max_parallel to avoid rate limits
3. Increase timeout if needed:

"execution_config": {
  "timeout_seconds": 7200
}

---

Model API Errors

Error: "Rate limit exceeded"

Solution:

1. Reduce max_parallel in list_emit_await
2. Add delays between requests
3. Use a different model/provider

Error: "Invalid API key"

Solution:

1. Verify key in Jetty secrets
2. Check key hasn't expired
3. Ensure key has required permissions

---

File Upload Issues

Files not accessible in workflow

Cause: Incorrect path reference.

Solution: Use init_params.file_paths[0] for uploaded files:

{
  "read_file": {
    "activity": "gemini_file_reader",
    "asset_path": "init_params.file_paths[0]"
  }
}

File too large

Solution:

• Check file size limits for your plan
• Consider chunking large documents
• Use async execution for large files

---

Debugging Tips

1. Check Workflow Logs

curl "https://flows-api.jetty.io/api/v1/workflows-logs/WORKFLOW_ID" \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

2. Inspect Trajectory State

curl "https://flows-api.jetty.io/api/v1/db/trajectory/COLLECTION/TASK/TRAJ_ID" \
  -H "Authorization: Bearer $JETTY_API_TOKEN" | jq

3. Test Steps Individually

Create a minimal workflow with just the failing step to isolate issues.

4. Validate JSON Configuration

Use jq to check for syntax errors:

cat workflow.json | jq .

5. Check Step Template Schema

curl "https://flows-api.jetty.io/api/v1/step-templates/activity_name" | jq

---

Common Path Expression Patterns

Pattern	Meaning
init_params.field	Input parameter
step_name.outputs.text	Step output
step_name.outputs.images[0].path	First image path
step_name.outputs.images[*].path	All image paths (array)
step_name.inputs.param	Step input