Skip to main content

Troubleshooting & FAQ

This page covers the most common issues encountered when working with Zeq OS, the SDK, API Gateway, Sync Engine, and Docker deployments. If your problem is not listed here, check the GitHub Issues or ask in the community chat.

Common API Errors​

These are the most frequently returned error codes from the API Gateway (port 4000) and the SDK.

Error CodeHTTP StatusCauseFix
operator_not_found404The requested operator ID does not exist in the registry.Verify the operator ID against the API Gateway Reference. IDs are case-sensitive (e.g., KO42, not ko42).
precision_failure422The computation result exceeds the mandatory ≤0.1% precision threshold.Re-run with tighter parameters, provide explicit domain_hints, or reduce query complexity. See Precision Problems below.
desync409HulyaPulse phase mismatch between client and server.Check clock synchronization. Ensure both sides reference the same NTP source. See HulyaPulse Synchronization Issues.
rate_limited429Too Many Requests. Default limit is 100 requests per minute per API key.Back off and retry with exponential backoff. To raise the limit, set ZEQ_RATE_LIMIT in your environment or configure it in gateway.yml.
unauthorized401Missing or invalid X-API-Key header.Include a valid API key: X-API-Key: your-key-here. Generate keys via the Gateway admin endpoint or set ZEQ_API_KEYS in your .env file.
timeout504The computation exceeded the server-side time limit (default 30 seconds).Simplify the query, reduce operator count, or increase the timeout via ZEQ_COMPUTE_TIMEOUT environment variable.

Example: handling errors in Python

from zeq_os import ZeqProcessor, ZeqError

processor = ZeqProcessor()

try:
    result = processor.process("extremely complex multi-domain query")
except ZeqError as e:
    if e.code == "precision_failure":
        # Retry with domain hints to improve operator selection
        result = processor.process(
            "extremely complex multi-domain query",
            domain_hints=["quantum_mechanics", "general_relativity"]
        )
    elif e.code == "rate_limited":
        print(f"Rate limited. Retry after {e.retry_after} seconds.")
    else:
        raise

HulyaPulse Synchronization Issues​

HulyaPulse operates at exactly 1.287 Hz (one tick every 0.777 seconds, known as a Zeqond). Synchronization problems occur when the client and server drift apart.

Clock Drift​

Symptom: desync errors or gradually degrading phase coherence values.

Cause: The local system clock has drifted more than 1 Zeqond (0.777s) from the server reference.

Fix:

  1. Enable NTP synchronization on all participating nodes:
# Linux (systemd)
sudo timedatectl set-ntp true

# macOS
sudo sntp -sS time.apple.com
  1. Verify drift is below threshold:
# Check current offset
ntpq -p | grep -E '^\*'
# Offset should be < 100ms for reliable sync

Phase Mismatch​

Symptom: WebSocket ticks arrive but phase_coherence drops below 99%.

Cause: The client is computing phase values from a stale reference timestamp.

Fix:

  • Reconnect the WebSocket to receive a fresh baseline tick.
  • Ensure your client uses the timestamp field from each tick (not the local clock) for phase calculations.
  • If using the SDK, call processor.resync() to force a phase realignment.

KO42 Not Applied​

Symptom: Computations return results but precision is poor, or the API returns operator_not_found for expected operators.

Cause: KO42 is the mandatory metric tensioner operator. If it is missing from the operator chain, all downstream calculations lose their calibration anchor.

Fix:

  • The SDK automatically includes KO42. If you are calling the API directly, ensure your request body includes "operators": ["KO42", ...].
  • Verify that operator-registry.json is present and not corrupted.
  • Re-pull the registry: zeq-cli registry update.

Precision Problems​

The Zeq OS framework enforces a ≤0.1% precision target on all computations. When this target is not met, the system returns a precision_failure error.

Result Deviation Exceeds 0.1%​

Common causes:

  1. Incorrect operator selection -- the auto-selector chose operators for the wrong domain.
  2. Unit mismatch -- input values are in unexpected units (e.g., miles instead of meters).
  3. Operator saturation -- the 4-operator maximum was hit and critical operators were excluded.

Fix:

# Provide explicit domain hints to guide operator selection
result = processor.process(
    "gravitational lensing angle",
    domain_hints=["general_relativity", "astrophysics"]
)

check = result.precision_check()
print(f"Precision: {check.actual_precision:.4f}%")

Re-calibration Steps​

If precision degrades across multiple queries:

  1. Clear the processor cache: processor.clear_cache()
  2. Reload the operator registry: processor.reload_registry()
  3. Verify KO42 is in the active operator set.
  4. Re-run a known-good calibration query:
# Calibration query with known expected output
cal = processor.process("speed of light in vacuum")
assert cal.precision_check().within_tolerance, "Calibration failed"

Using AutoTune for Automatic Precision Adjustment​

AutoTune iteratively adjusts operator weights until precision falls within tolerance:

from zeq_os import ZeqProcessor, AutoTune

processor = ZeqProcessor()
tuner = AutoTune(processor, target_precision=0.05)  # 0.05% target

result = tuner.run("muon lifetime at rest")
print(f"AutoTune iterations: {result.iterations}")
print(f"Final precision:     {result.precision:.4f}%")
print(f"Operators used:      {result.operators}")

AutoTune will run up to 10 iterations by default. Override with max_iterations=N.

Docker & Deployment Issues​

Port Conflicts​

Zeq OS services use these ports by default:

PortService
80Nginx reverse proxy
3000Docusaurus documentation
3002Sync Chrome Extension UI
3003Zeq Git
3080Zeq MI
4000API Gateway
4001Sync Engine
8044Zeq Daemon

Fix: Check for conflicts before starting:

# Check if a port is already in use
lsof -i :4000

# Override ports in docker-compose.override.yml
# Example: move API Gateway to port 4010
# ports:
#   - "4010:4000"

Container Health Check Failures​

Symptom: docker compose ps shows containers as unhealthy.

Fix:

# Check container logs for the failing service
docker compose logs api-gateway --tail 100

# Common causes:
# 1. Dependent service not ready yet -- increase health check interval
# 2. Missing environment variables -- check .env file
# 3. Database connection refused -- ensure db container started first

Volume Mount Issues​

Symptom: Docusaurus or other services cannot find expected files.

Fix:

# Verify the volume mount paths match your local directory structure
docker compose config | grep -A 3 volumes

# Common issue: docs path mismatch
# Wrong:  ./documentation:/app/docs
# Right:  ./docs:/app/docs

SSL Certificate Not Found​

Symptom: Nginx fails to start with ssl_certificate not found.

Fix for local development:

# Comment out the HTTPS server block in nginx.conf for local dev:
# server {
#     listen 443 ssl;
#     ssl_certificate /etc/ssl/certs/zeq.crt;
#     ssl_certificate_key /etc/ssl/private/zeq.key;
#     ...
# }

Or generate a self-signed certificate:

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout ssl/zeq.key \
  -out ssl/zeq.crt \
  -subj "/CN=localhost"

Missing Environment Variables​

Symptom: Services crash on startup with KeyError or undefined errors.

Required variables:

# .env (minimum required)
JWT_SECRET=your-random-secret-here
ZEQ_API_KEYS=key1,key2,key3
HULYA_FREQ=1.287
ZEQOND=777
GATEWAY_PORT=4000
SYNC_PORT=4001

Generate a secure JWT secret:

openssl rand -hex 32

SDK Installation Issues​

Python​

# Install in a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate
pip install zeq-os

# Verify installation
python -c "from zeq_os import ZeqProcessor; print('OK')"

Common issues:

  • Python version: Requires Python 3.10+. Check with python --version.
  • Conflicting packages: If you get import errors, try pip install --force-reinstall zeq-os.
  • Apple Silicon (M1/M2/M3/M4): If native extensions fail, install Rosetta: softwareupdate --install-rosetta.

JavaScript / Node.js​

# Install via npm
npm install @zeq-os/sdk

# Or with yarn
yarn add @zeq-os/sdk

ESM vs CommonJS:

// ESM (recommended, package.json: "type": "module")
import { ZeqProcessor } from '@zeq-os/sdk';

// CommonJS (legacy)
const { ZeqProcessor } = require('@zeq-os/sdk');

Common issues:

  • Node version: Requires Node 18+. Check with node --version.
  • ERR_REQUIRE_ESM: You are using require() on an ESM-only package. Switch to import or set "type": "module" in your package.json.

Rust​

# Add to Cargo.toml
# [dependencies]
# zeq-os = "0.1"

cargo build

Common issues:

  • operator-registry.json not found: Set the ZEQ_REGISTRY_PATH environment variable or place the file in your project root.
  • Missing Rust toolchain: Install via curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh.
  • Linking errors on Linux: Install build-essential and pkg-config.

Performance Optimization​

Batch Processing vs Sequential​

For multiple queries, batch processing is significantly faster due to shared operator initialization:

from zeq_os import ZeqProcessor

processor = ZeqProcessor()

# Slow: sequential processing
queries = ["query1", "query2", "query3"]
results = [processor.process(q) for q in queries]

# Fast: batch processing (shares operator context)
results = processor.process_batch(queries)

Batch processing reuses the operator registry lookup across all queries, reducing per-query overhead by approximately 40%.

Pipeline Operator Chaining​

Chain operators explicitly when you know the computation flow to avoid redundant domain detection:

from zeq_os import ZeqProcessor, Pipeline

pipeline = Pipeline([
    ("detect_domain", {}),
    ("select_operators", {"max_operators": 4}),
    ("compute", {"precision_target": 0.05}),
    ("verify", {}),
])

result = pipeline.execute("relativistic momentum at 0.95c")

Connection Pooling for WebSocket Sync​

When running multiple dashboard clients or services, use connection pooling to reduce server load:

import { SyncPool } from '@zeq-os/sdk';

// Create a pool with max 5 connections
const pool = new SyncPool('ws://localhost:4001/ws', {
  maxConnections: 5,
  reconnectInterval: 777, // 1 Zeqond
});

pool.on('tick', (tick) => {
  console.log(`Zeqond: ${tick.zeqond}, Phase: ${tick.phase}`);
});

pool.connect();

Rate Limiting Configuration​

Adjust rate limits based on your deployment needs:

# gateway.yml
rate_limiting:
  default: 100        # requests per minute (default)
  burst: 20           # burst allowance above the limit
  per_key: true       # rate limit per API key (not global)

  # Override for specific endpoints
  overrides:
    /compute: 50       # heavier endpoint, lower limit
    /health: 1000      # health checks can be frequent

Or set via environment variable:

export ZEQ_RATE_LIMIT=200  # 200 requests per minute

Glossary​

Quick reference for Zeq OS terminology used throughout the documentation.

TermDefinition
HulyaPulseThe universal synchronization frequency of Zeq OS, operating at exactly 1.287 Hz. All computations, encryption, and data sync are phase-locked to this pulse.
ZeqondThe fundamental time unit of Zeq OS, equal to 0.777 seconds (1 / 1.287 Hz). Used as the base interval for synchronization, reconnection delays, and tick scheduling.
KO42The mandatory metric tensioner operator included in every Zeq OS computation. KO42 provides the calibration anchor that all other operators reference. Without it, precision guarantees do not hold.
PLATPhase-Locked Authentication Tag. A cryptographic tag derived from the current HulyaPulse phase, used to authenticate messages and verify temporal integrity.
HITEHulyaPulse-Integrated Thermodynamic Encryption. The encryption system used by Zeq OS, combining AES-256-GCM with phase-synchronized entropy and Landauer-certified thermodynamic proofs.
TESCTemporal Entangled State Channels. A communication protocol that maintains quantum-inspired entanglement between channel endpoints, ensuring state consistency across distributed nodes.
MIMathematical Intelligence. The core computation engine of Zeq OS that evaluates physics queries using the 7-Step Protocol and the HULYAS Master Equation.
Landauer CertificateA thermodynamic proof embedded in every HITE-encrypted file. It calculates the minimum energy required to brute-force the encryption, demonstrating that decryption without the key is physically impossible (energy exceeds trillions of sun-lifetimes).
7-Step ProtocolThe standardized computation pipeline: (1) Parse query, (2) Detect domains, (3) Select operators, (4) Apply KO42, (5) Compute master sum, (6) Verify precision, (7) Return ZeqState.
Master SumThe primary numerical output of a Zeq OS computation, produced by the HULYAS Master Equation after all selected operators have been applied.
Phase CoherenceA percentage (0-100%) indicating how well-aligned the computation is with the HulyaPulse reference signal. Values above 99% indicate excellent synchronization.
ZeqStateThe result object returned by every Zeq OS computation, containing domains, operators, master sum, phase coherence, zeqond timestamp, and precision metadata.
OperatorA mathematical function unit in Zeq OS. There are 1,576 operators across 64 physics domains. Each computation uses at most 4 operators (plus the mandatory KO42).
AutoTuneAn iterative optimization routine that automatically adjusts operator weights and parameters until the computation meets a specified precision target.

Still Stuck?​

  • GitHub Issues: github.com/zeq-os/zeq-os-hub/issues
  • API Status: Check http://localhost:4000/health for Gateway health.
  • Sync Status: Check http://localhost:4001/health for Sync Engine health.
  • Logs: docker compose logs -f to tail all service logs.
  • Community: Join the Zeq Chat at http://localhost:3007.