---
title: Troubleshooting | Lightcone
description: Solutions for common issues with Lightcone browser sessions, authentication, and Agent Tasks.
---

This page covers common issues and how to resolve them. If your issue isn’t listed here, check the [API Reference](/api/index.md) 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](https://lightcone.ai/developer) 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](https://lightcone.ai/developer)

## 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](/integrations/playwright/index.md) with CSS selectors instead of coordinates, or use the [Responses API](/guides/responses-api/index.md) 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**:

Terminal window

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

### TypeScript: `Cannot find module '@tzafon/lightcone'`

**Fix**:

Terminal window

```
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](/api/index.md) for detailed endpoint documentation and error codes
- Review the [Quickstart](/guides/quickstart/index.md) to verify your setup is correct
- Contact support through the [dashboard](https://lightcone.ai/developer)