Onboarding Troubleshooting

This guide covers common device onboarding issues and their solutions.

Quick Diagnostics

Run these checks first:

Check	How	Expected
Claim exists	Console → Devices → Pending	Device listed
ACAP installed	Camera web UI → Apps	Anava Agent running
Network access	Camera can reach internet	Yes
Time sync	Camera web UI → System → Date	Correct time

Common Issues

Device Stuck in "Pending"

Symptoms:

• Claim created in Console
• Device never transitions to "Online"
• May stay pending for hours

Causes & Solutions:

1. ACAP not installed

   Camera Web UI → Apps
   - Verify "Anava Agent" is listed
   - Status should be "Running"
   - If not installed, download from Console → Downloads

2. ACAP installed but not running

   Camera Web UI → Apps → Anava Agent → Start

3. Network connectivity

   # From camera network, verify connectivity:
   curl -v https://api.anava.ai/health
   # Should return 200 OK
   
   # Test MQTT port:
   nc -zv mqtt.anava.ai 8884
   # Should show "Connection succeeded"

4. Firewall blocking

   • Ensure port 8884 (MQTT) OR 443 (HTTPS) is open outbound
   • Check corporate proxy settings

5. Serial number mismatch

   • Verify serial in claim matches device exactly
   • Check for typos (0 vs O, 1 vs I)
   • Serial is case-sensitive

"Certificate Verification Failed"

Symptoms:

• Device attempts to bootstrap
• Receives certificate error
• Shows as "Failed" in Console

Causes & Solutions:

1. Firmware too old

   Camera Web UI → System → Maintenance → Upgrade
   - Firmware must be AXIS OS 10.0 or later
   - Older firmware lacks DeviceID certificate

2. DeviceID certificate missing

   Camera Web UI → System → Security → Certificates
   - Look for "Axis Device ID" certificate
   - If missing, contact Axis support

3. Time synchronization

   Camera Web UI → System → Date and time
   - Enable "Synchronize with NTP"
   - Verify time is accurate (within 5 minutes)
   - Certificate validation fails with wrong time

4. Corporate proxy intercepting TLS

   • Check if proxy performs TLS inspection
   • Anava requires end-to-end mTLS
   • May need to bypass proxy for Anava endpoints

"Claim Expired"

Symptoms:

• Claim was created but device didn't connect in time
• Console shows "Claim expired"

Solution:

1. Delete the expired claim
2. Create a new claim for the same serial number
3. Claims expire after 24 hours for security
4. Ensure device is connected to network before claiming

"Device Already Claimed"

Symptoms:

• Attempting to claim device
• Error: "Device already claimed"

Causes & Solutions:

1. Device in another organization

   • Contact previous owner to release
   • Or contact Anava support with proof of ownership

2. Device in same organization, different group

   Console → Devices → All
   - Search for serial number
   - Device may already be provisioned
   - Reassign to desired group if needed

3. Orphaned claim

   • Old claim may exist from failed attempt
   • Console → Devices → Pending → Delete old claim
   • Create new claim

Bootstrap Succeeds but Device Goes Offline

Symptoms:

• Device provisions successfully
• Shows online briefly
• Then goes offline

Causes & Solutions:

1. Credential storage issue

   Camera Web UI → Apps → Anava Agent → Stop
   Wait 5 seconds
   Camera Web UI → Apps → Anava Agent → Start

2. Memory pressure

   • Check camera's overall memory usage
   • Other apps may be consuming resources
   • Consider disabling unused camera apps

3. MQTT connection dropping

   • Check network stability
   • View ACAP logs for disconnect reasons
   • May indicate network instability

HTTP Fallback Not Working

Symptoms:

• MQTT bootstrap fails (expected)
• HTTP fallback also fails
• Device cannot provision

Causes & Solutions:

1. Both ports blocked

   Required: Port 443 (HTTPS) for fallback
   Test: curl -v https://api.anava.ai/health

2. Corporate proxy

   • HTTP fallback uses standard HTTPS
   • Should work through most proxies
   • Check proxy logs for blocked requests

3. TLS version mismatch

   • Anava requires TLS 1.2 or 1.3
   • Old camera firmware may only support TLS 1.0/1.1
   • Update firmware to resolve

Diagnostic Commands

View Bootstrap Logs

From camera web UI:

System → Logs → Application Log
Filter: "anava" or "bootstrap"

Example log entries:

[INFO] Bootstrap: starting provisioning
[INFO] Bootstrap: loaded DeviceID certificate (serial: ACCC8EF12345)
[INFO] Bootstrap: attempting MQTT bootstrap to mqtt.anava.ai:8884
[WARN] Bootstrap: MQTT failed (timeout), trying HTTP fallback
[INFO] Bootstrap: HTTP bootstrap to api.anava.ai
[INFO] Bootstrap: credentials received, storing
[INFO] Bootstrap: provisioning complete

Check Certificate

From camera web UI:

System → Security → Certificates

Should show:

• Axis Device ID: Status "Valid"
• Expiry date in the future (typically 10+ years)

Verify ACAP Status

From camera web UI:

Apps → Anava Agent → About

Shows:

• Version number
• Status (Running/Stopped)
• Last error (if any)

Network Requirements

Minimum Requirements

Endpoint	Port	Protocol	Required For
mqtt.anava.ai	8884	MQTT/TLS	Primary bootstrap & operation
api.anava.ai	443	HTTPS	HTTP fallback bootstrap

Firewall Rules

# Allow outbound MQTT
iptables -A OUTPUT -p tcp --dport 8884 -d mqtt.anava.ai -j ACCEPT

# Allow outbound HTTPS (fallback)
iptables -A OUTPUT -p tcp --dport 443 -d api.anava.ai -j ACCEPT

Proxy Configuration

If using HTTP proxy:

Camera Web UI → System → Network → Proxy
- HTTP Proxy: your-proxy.company.com:8080
- HTTPS Proxy: your-proxy.company.com:8080
- No Proxy: mqtt.anava.ai (if MQTT port open)

Note: MQTT cannot traverse HTTP proxies. If only HTTP proxy is available, ensure the HTTP fallback path works.

Recovery Procedures

Full Reset and Re-provision

1. Delete claim in Console

   Console → Devices → Find device → Delete

2. Uninstall ACAP

   Camera Web UI → Apps → Anava Agent → Uninstall

3. Clear credentials (optional, handled by uninstall)

   Camera Web UI → System → Maintenance → Factory Default
   Select: "Only application data"

4. Reinstall and reclaim

   • Install ACAP from Console → Downloads
   • Create new claim
   • Wait for provisioning

Export Diagnostics

For support escalation:

1. Console:

   Devices → {Device} → Actions → Download Diagnostics

2. Camera:

   Camera Web UI → System → Logs → Download all logs

3. Network capture (advanced):

   # From device network
   tcpdump -i eth0 host mqtt.anava.ai or host api.anava.ai -w capture.pcap

Related Documentation

• Overview - Feature introduction
• Bootstrap Flow - Technical sequence details
• PKI Authentication - Certificate deep-dive

---

Last updated: December 2025