> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common setup, calling, SIP, agent, database, and CRM issues.

## No Calls Are Starting

Check:

* Current time is within `CALL_HOURS_START` and `CALL_HOURS_END`.
* Current weekday is in `CALL_ALLOWED_WEEKDAYS`.
* Lead status is `new`.
* `retry_after` is empty or in the past.
* `MAX_CONCURRENT_CALLS` is not blocked by stuck `calling` rows.
* `CALL_WHITELIST_NUMBERS` is empty or includes the test number.

Useful SQL:

```sql theme={null}
SELECT id, name, phone, status, retry_after, retry_count
FROM leads
ORDER BY created_at DESC
LIMIT 20;
```

## SIP Call Fails To Start

Check:

* `LIVEKIT_SIP_TRUNK_ID` is set.
* The ID is an outbound trunk ID, not inbound.
* `VOBIZ_SIP_DOMAIN`, `VOBIZ_SIP_USERNAME`, and `VOBIZ_SIP_PASSWORD` are correct.
* `VOBIZ_PHONE_NUMBER` is valid E.164.
* Target phone normalizes to `+91XXXXXXXXXX`.

Run:

```powershell theme={null}
python sip_setup.py list
python sip_setup.py call +91XXXXXXXXXX
```

## Invalid Phone Numbers

The scheduler rejects numbers that cannot safely become Indian E.164 mobile numbers.

Accepted examples:

```text theme={null}
98765XXXXX
098765XXXXX
9198765XXXXX
+9198765XXXXX
```

Rejected examples:

```text theme={null}
12345
fb_psid_123
+1 555 123 4567
```

## Calls Stuck In `calling`

The scheduler automatically fails stale calls older than:

```env theme={null}
STALE_CALL_MINUTES=5
```

Manual inspection:

```sql theme={null}
SELECT id, lead_id, phone, call_room, updated_at
FROM calls
WHERE status='calling'
ORDER BY updated_at ASC;
```

## Agent Does Not Join The Room

Check:

* The correct agent process is running.
* Room name starts with `ignitech-lead-`.
* SIP participant identity starts with `sip-lead-`.
* LiveKit credentials match the same project where SIP is configured.
* The agent can connect to PostgreSQL using `DATABASE_URL`.

## Talking Shops Push Fails

Check:

* `TALKINGSHOPS_API_URL`
* `TALKINGSHOPS_API_KEY`
* `TALKINGSHOPS_AUTH_HEADER`
* Optional `TALKINGSHOPS_AUTH_PREFIX`
* Customer endpoint derivation or `TALKINGSHOPS_CUSTOMERS_API_URL`

For safe testing:

```env theme={null}
TALKINGSHOPS_DRY_RUN=true
```

If you want failed pushes to retry later:

```env theme={null}
TALKINGSHOPS_MARK_FAILED_ON_PUSH_ERROR=false
```

## Database Connection Errors

Check:

* `DATABASE_URL` is set.
* PostgreSQL is running.
* Docker uses host `db`, local runs usually use `localhost`.
* The database user has permission to create tables and triggers.

Initialize:

```powershell theme={null}
python db.py
```

## LiveKit/WebRTC Runtime Panic

If a native WebRTC error appears after dependency or environment changes, recreate the virtual environment:

```powershell theme={null}
Remove-Item -Recurse -Force .venv
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
```

Then run with extra logs:

```powershell theme={null}
$env:RUST_BACKTRACE="1"
$env:RUST_LOG="livekit=debug"
python agent_realtime.py start
```

## Qualification Is Empty

Likely causes:

* Lead rejected or hung up before answering.
* Audio did not reach the agent.
* The call ended before extraction.
* Model credentials are missing.
* Transcript was too short.

Check the `calls.failure_reason` and agent logs.