Troubleshooting

This page covers common issues and how to resolve them. If your issue isn’t listed here, check the API Reference for detailed error responses or contact support.

Authentication errors

”Invalid API key” or 401 response

Your API key is missing, expired, or incorrect.

Fix:

1. Verify the key is set: echo $TZAFON_API_KEY
2. Check it starts with sk_
3. Regenerate the key in the dashboard if needed
4. If passing the key explicitly, ensure there are no extra spaces or newline characters

# Verify the SDK is picking up the key
from tzafon import Lightcone
client = Lightcone()
print(client.api_key[:10])  # Should print "sk_your_ap..."

import Lightcone from "@tzafon/lightcone";
const client = new Lightcone();
// The SDK throws AuthenticationError immediately on 401

429 Too Many Requests

You’ve exceeded the rate limit for your plan.

Fix:

• Reduce the number of concurrent sessions
• Add delays between rapid API calls
• The SDKs retry automatically (default: 2 retries with exponential backoff)
• Check your plan’s concurrent session limit in the dashboard

Session issues

Session times out unexpectedly

Sessions have two timeout mechanisms. Either can terminate your session:

Timeout	What it does
timeout_seconds	Maximum session lifetime, regardless of activity
inactivity_timeout_seconds	Kills the session after a period with no API calls

Fix:

• Increase timeouts when creating the session:

  with client.computer.create(
      kind="browser",
      timeout_seconds=3600,          # 1 hour max
      inactivity_timeout_seconds=300, # 5 minutes idle
  ) as computer:
      # ...

• Call computer.keep_alive() during long pauses between actions
• Set auto_kill=False to disable the inactivity timeout entirely (the session will still respect timeout_seconds)

“Session not found” after creation

The session was created but terminated before you used it — usually because of the inactivity timeout.

Fix: Start interacting with the session immediately after creating it. If you need to create sessions in advance, set a longer inactivity_timeout_seconds.

Session creation hangs or is slow

Session creation typically takes 2–5 seconds. If it’s slower:

Fix:

• Check your network connection to api.tzafon.ai
• Increase the SDK timeout: Lightcone(timeout=60.0)
• If creating many sessions in parallel, you may be hitting your plan’s concurrent session limit

Browser automation issues

Clicks land in the wrong place

Coordinates are screenshot pixel positions. If the page layout has changed since you determined the coordinates, clicks will miss their target.

Fix:

1. Take a fresh screenshot before each interaction
2. Open the screenshot URL to verify the current page layout
3. Use the coordinates you see in the screenshot, not hardcoded values
4. If the viewport was resized, coordinates shift — check display settings match your expectations

# Always screenshot first to find current coordinates
result = computer.screenshot()
print(computer.get_screenshot_url(result))
# Open the URL, note the coordinates, then click

const result = await client.computers.screenshot(id);
console.log(result.result?.screenshot_url);
// Check the screenshot, then use the correct coordinates

For more reliable element targeting, use the Playwright integration with CSS selectors instead of coordinates, or use the Responses API to let a vision model find click targets automatically.

Page doesn’t load or shows blank content

The page may not have finished loading before you interacted with it.

Fix:

• Add computer.wait(2) or computer.wait(3) after navigate()
• For JavaScript-heavy pages (SPAs), wait longer — up to 5 seconds
• Take a screenshot after waiting to confirm the page rendered
• Some pages require scrolling or clicking to trigger lazy-loaded content

Bot detection blocks the browser

Some websites detect and block automated browsers.

Fix:

• Enable the advanced proxy: client.computer.create(kind="browser", use_advanced_proxy=True)
• The advanced proxy routes traffic through residential IPs with realistic browser fingerprints
• For especially strict sites, add realistic human-like delays between actions
• Check the site’s robots.txt — if the site explicitly blocks automation, respect their wishes

HTML extraction returns empty or partial content

computer.html() captures the current DOM state. If the page is still loading, you’ll get incomplete content.

Fix:

• Wait for the page to fully render before calling html()
• For SPAs that load content dynamically, wait for specific content to appear (take screenshots to verify)
• Some content may be in iframes — html() captures the main frame only

Agent Task issues

Agent gets stuck or loops

The agent may repeat the same actions without making progress.

Fix:

• Set max_steps to limit the number of actions: client.agent.tasks.start(instruction="...", kind="browser", max_steps=20)
• Write more specific instructions — tell the agent exactly what “done” looks like
• Use inject_message() to redirect a stuck agent
• Pause and inspect: client.agent.tasks.pause(task_id), then check the latest screenshot

Agent completes but with wrong results

Fix:

• Be specific in your instructions: “Go to amazon.com, search for ‘mechanical keyboard’, sort by price low to high, and screenshot the first 3 results” works better than “find cheap keyboards”
• Include success criteria: “You’re done when you can see the order confirmation page”
• Use streaming (start_stream) to watch the agent’s progress in real time and redirect if needed

Agent task fails with exit code 1

A non-zero exit code means the agent encountered an error or couldn’t complete the task.

Fix:

• Check the task status for error details: client.agent.tasks.retrieve_status(task_id)
• Common causes: session timed out, page blocked the browser, instruction was ambiguous
• Retry with a longer timeout_seconds or max_steps

Responses API issues

”computer_call_output” errors

When chaining responses with previous_response_id, the call_id must match the computer_call from the previous response.

Fix:

# Extract the call_id from the computer_call in the response
for item in response.output:
    if item.type == "computer_call":
        call_id = item.call_id  # Use this exact value

# Feed it back
followup = client.responses.create(
    previous_response_id=response.id,
    input=[{
        "type": "computer_call_output",
        "call_id": call_id,  # Must match
        "output": {"type": "input_image", "image_url": screenshot_url},
    }],
    # ...
)

SDK errors

Python: ModuleNotFoundError: No module named 'tzafon'

The SDK isn’t installed in your current Python environment.

Fix:

pip install tzafon
# Or if using a virtual environment:
python -m pip install tzafon

TypeScript: Cannot find module '@tzafon/lightcone'

Fix:

npm install @tzafon/lightcone
# Verify it's in node_modules:
ls node_modules/@tzafon/lightcone

TypeScript: non-null assertions (computer.id!)

The TypeScript SDK returns optional fields. The id field is always present after creation, but TypeScript’s type system doesn’t know that.

Fix: Use the non-null assertion operator (!) as shown in the examples, or assign to a variable with a check:

const computer = await client.computers.create({ kind: "browser" });
if (!computer.id) throw new Error("No session ID returned");
const id = computer.id;

Still stuck?

• Check the API Reference for detailed endpoint documentation and error codes
• Review the Quickstart to verify your setup is correct
• Contact support through the dashboard