Agent registers but never appears in the console

Symptom

The agent starts, posts to /provision, and the backend responds with "Device registered successfully". The device never appears in the console device list, or it appears briefly and then shows offline.

Cause

The agent is talking to a different server than the one your browser is pointed at — for example, the agent has a stale ServerURL that points to an old or test server. The registration lands in a different database the console does not read. A second common cause is an expired or revoked device API key: the backend returns an authentication error and the agent silently retries.

Fix

The agent reads two configuration files: /etc/otapulse/otapulse.conf and the persistent otapulse.conf (see Configuration files). The /etc file wins when both set a field. On Yocto images the persistent file is /data/otapulse/otapulse.conf. In other installs it is /var/lib/otapulse/otapulse.conf unless OTAPULSE_DATASTORE_DIR says otherwise.

On the device, check the agent log and the server URL. The grep shows the URL and the device ID, not the key:

journalctl -u soc-ota-agent --since "5 min ago" --no-pager
grep -E 'ServerURL|UseSoCMonitoring|SoCDeviceID' /etc/otapulse/otapulse.conf /data/otapulse/otapulse.conf

Wrong server URL

Edit ServerURL in /etc/otapulse/otapulse.conf, then restart the agent. The file is JSON, so use a text editor or a small script:

python3 -c "
import json
c = json.load(open('/etc/otapulse/otapulse.conf'))
c['ServerURL'] = 'https://<your-server>'
json.dump(c, open('/etc/otapulse/otapulse.conf','w'), indent=4)
"
systemctl restart soc-ota-agent

Caution

On an image-based device this edit lasts only until the next A/B slot switch. Each image ships its own /etc/otapulse/otapulse.conf with the ServerURL it was built with, and the /etc file overrides the persistent one. To fix the URL for good, rebuild the image and your update artifacts with the correct server URL (OTA_SERVER_URL in Yocto).

Invalid device API key

Create a new key under API Keys in the console sidebar. Then set it as SoCAPIKey, in the file where the old key lives. If SoCAPIKey appears in /etc/otapulse/otapulse.conf, change it there. Otherwise change it in the persistent file, which is the one first-boot provisioning wrote. If your config sets UseSoCMonitoring to false or omits it, the agent uses TenantToken instead.

python3 -c "
import json
path = '/data/otapulse/otapulse.conf'  # or /etc/otapulse/otapulse.conf
c = json.load(open(path))
c['SoCAPIKey'] = '<your-new-device-api-key>'
json.dump(c, open(path,'w'), indent=4)
"
systemctl restart soc-ota-agent