The Panel shows "License Required" on the dashboard, or write operations (creating accounts, issuing certificates, etc.) return a 403 with "error": "license_required". The Agent is running and reachable, but it is refusing to carry out write operations due to a license problem.
The Agent validates the license at startup and every 24 hours thereafter. Reads (viewing account lists, status checks) are always permitted. Only writes are blocked.
Step 1: Check License Status
Query the Agent's license status endpoint directly:
curl http://127.0.0.1:7443/license/status
The response tells you exactly what the Agent knows:
{
"valid": false,
"plan": "free",
"max_accounts": 5,
"max_servers": 1,
"expires_at": "2026-03-01T00:00:00Z",
"message": "License is already activated on 1 of 1 allowed servers."
}
Common rejection reasons:
| Reason | Meaning |
|---|---|
expired |
License past its expiration date |
suspended |
License manually suspended (billing issue) |
cancelled |
License cancelled |
invalid_key |
Key not found on opterius.com |
server_limit_reached |
Too many active servers using this license |
unreachable |
Agent cannot reach opterius.com to verify |
Step 2: Check the License Cache
The Agent caches the last successful license verification:
cat /etc/opterius/license-cache.json
This shows the last known-good state. If the cache is stale or empty, the Agent could not reach opterius.com for re-verification.
Common Causes and Fixes
License expired
The most common cause. Renew at opterius.com. After payment processes, restart the Agent to trigger an immediate re-check:
systemctl restart opterius-agent
Server limit reached (server_limit_reached)
Your license is already activated on the maximum number of servers your plan allows. Each unique server IP that calls /api/license/verify consumes one activation slot.
Fix options:
-
Revoke an unused activation — go to opterius.com → Dashboard → Licenses, find your license, and click Revoke on any IP that's no longer in use. The slot is freed immediately, and a new server can register on its next license check.
-
Wait for stale auto-expiry — activations that haven't checked in for 7+ days are automatically marked Inactive and don't count toward your limit. After 30 days they're deleted entirely. If your old server is offline, just wait or revoke it manually.
-
Upgrade your plan — Business allows 5 servers, Datacenter is unlimited.
See Adding Servers for details on the activation system.
Agent cannot reach opterius.com (unreachable)
The Agent verifies licenses by calling https://opterius.com/api/license/verify. If outbound HTTPS is blocked, verification fails. Test:
curl -v https://opterius.com/api/license/verify -X POST
If this times out or is refused, your server's firewall is blocking outbound port 443. Allow it:
# ufw
ufw allow out 443/tcp
# iptables
iptables -I OUTPUT -p tcp --dport 443 -j ACCEPT
Many cloud providers (Linode, AWS, DigitalOcean, etc.) also have external firewall rules (security groups / cloud firewall rules in the control panel) separate from the OS firewall — check those too.
While opterius.com is unreachable, the Agent runs on its cached license for up to 48 hours. After that, it falls into restricted mode and blocks writes until reachability is restored.
Invalid key (invalid_key)
The license key in /etc/opterius/agent.conf doesn't exist on opterius.com. Possible causes:
- Typo — verify the key matches what's shown at opterius.com → Dashboard → Licenses.
- Deleted — if you (or someone with admin access) deleted the license at opterius.com, it no longer validates.
- Wrong account — the license belongs to a different opterius.com account.
Fix: copy the correct key from your dashboard, paste it into the agent config, restart the agent:
nano /etc/opterius/agent.conf
# Update LICENSE_KEY=...
systemctl restart opterius-agent
Account limit reached (account_limit_reached)
If you're on a plan with max_accounts limit and you've reached it, creating a new account returns 403 with account_limit_reached (this is a separate error from license_required). Either delete an unused account or upgrade your plan.
Force Re-Verification
Restarting the Agent triggers an immediate license check on startup — it does not wait for the next scheduled verification interval:
systemctl restart opterius-agent
journalctl -u opterius-agent -n 20
The logs will confirm whether the license check passed or failed and why. Look for a line like:
License: valid (plan: free, max_accounts: 5, max_servers: 1, expires: ...)
Or, on failure:
License: INVALID — License is already activated on 1 of 1 allowed servers.