Common Error Messages

This guide explains common error messages you may encounter and how to resolve them.

Connection Errors

Connection Refused

The agent cannot establish a connection to the ZEM Cloud server.

Cause - The server is not reachable or not running
Solution - Verify the server URL is correct and the server is running
Check - Confirm network connectivity and firewall settings

Connection Timed Out

The connection attempt took too long and was abandoned.

Cause - Network issues, firewall blocking, or server overload
Solution - Check network connectivity and firewall rules
Check - Verify port 443 (HTTPS) is allowed outbound

Could Not Resolve Host

DNS lookup failed for the server hostname.

Cause - DNS configuration issues or incorrect hostname
Solution - Verify the server URL is spelled correctly
Check - Test DNS resolution with nslookup or dig

Authentication Errors

401 Unauthorised

The request was not authenticated properly.

Cause - Invalid or expired API key
Solution - Re-enrol the endpoint with a valid enrolment key
Check - Verify the API key in the agent configuration

403 Forbidden

The request was authenticated but access was denied.

Cause - Insufficient permissions or endpoint not recognised
Solution - Contact your administrator to verify endpoint status
Check - Confirm the endpoint appears in the dashboard

Certificate Errors

SSL Certificate Problem

The server's SSL/TLS certificate could not be verified.

Cause - Self-signed certificate, expired certificate, or hostname mismatch
Solution - Install a valid SSL certificate on the server
Check - Verify the certificate is trusted and not expired

Certificate Expired

The server's SSL certificate has passed its validity date.

Cause - Certificate not renewed before expiry
Solution - Renew the SSL certificate on the server
Check - Check certificate expiry date in browser

Permission Errors

Permission Denied (Agent)

The agent doesn't have sufficient system permissions.

Cause - Agent not running with elevated privileges
Solution - Ensure the agent runs as root (Linux/macOS) or Administrator (Windows)
Check - Verify service configuration and user permissions

Permission Denied (Dashboard)

Your user account doesn't have access to the requested feature.

Cause - Role doesn't include required permission
Solution - Contact administrator to request access
Check - Review your assigned role and permissions

Server Errors

500 Internal Server Error

An unexpected error occurred on the server.

Cause - Server-side bug or configuration issue
Solution - Check server logs for details
Check - Contact your system administrator

502 Bad Gateway

The server received an invalid response from an upstream service.

Cause - Backend service not responding
Solution - Restart the ZEM Cloud service
Check - Verify all server components are running

503 Service Unavailable

The server is temporarily unable to handle requests.

Cause - Server overload or maintenance
Solution - Wait and retry, or contact administrator
Check - Check if server is undergoing maintenance

Agent-Specific Errors

Queue Signature Verification Failed

The action from the server could not be verified.

Cause - Message tampering or configuration mismatch
Solution - Re-enrol the endpoint
Check - Verify there's no proxy modifying requests

Invalid Action Type

The server sent an unrecognised action command.

Cause - Version mismatch between server and agent
Solution - Update the agent to the latest version
Check - Verify agent and server versions are compatible

Machine ID Mismatch

The endpoint's identity doesn't match what the server expects.

Cause - Hardware change, VM clone, or re-enrolment issue
Solution - Unenrol and re-enrol the endpoint
Check - Delete the old endpoint from the dashboard first

Mobile-Specific Errors

Device Not Enrolled

The mobile device is not recognised by the server.

Cause - Enrolment token expired or invalid
Solution - Generate a new QR code and re-enrol
Check - Verify the device appears in Mobile Devices

Work Profile Creation Failed

Android could not create the managed Work Profile.

Cause - Missing Google account or policy restrictions
Solution - Sign in with a Google account before enrolling
Check - Ensure device allows Work Profiles

Action Not Supported

The requested action cannot be performed in the current management mode.

Cause - Action requires Device Owner mode but device is in Work Profile mode
Solution - Use only supported actions for the management mode
Check - Review management mode in device details