Skip to content

ASI‐OS Troubleshooting Field Guide

Jump to bottom
Cloudhabil edited this page Jan 11, 2026 · 1 revision

Rapid Diagnosis and Service Restoration

1.0 Foundational Checks: Validating Your Environment

Always validate the foundational environment first. Most failures are not in the core logic but in the setup. These checks prevent wasted time.

Initial System Prerequisites

Component Verification Command / Procedure
Python Version Verify the active Python version is 3.11 or newer: python --version.
Repository Integrity Ensure the repository has been cloned correctly: git clone https://github.com/Cloudhabil/AGI-Server.git.
Dependency Installation Confirm all required dependencies are installed: pip install -r requirements.lock or pip install ..

Common Installation Errors

  • Incorrect Python Version: An older version of Python will cause syntax errors or package failures. Confirm your active environment meets the 3.11+ requirement.
  • Failed Dependency Installation: Network issues or package conflicts can cause pip install to fail. Review the terminal output for specific error messages. A clean virtual environment is the best practice for isolation.
  • Incomplete Repository Clone: An interrupted git clone results in a corrupted local repository. If suspected, delete the directory and re-clone to ensure a valid code base.

With the environment's integrity confirmed, the next logical step is to troubleshoot the system's primary control interface.

2.0 The Unified CLI (manage.py): Diagnosing Command Failures

Any failure at the manage.py interface is a showstopper. Diagnosing its command patterns is the fastest path to identifying the system's high-level state.

server

Symptom Potential Cause & First Action
Server process fails to start in Sovereign-Loop mode. This indicates a problem with configuration or the boot sequence. First Action: Check the configs/ directory for malformed or missing files.
The server process starts but is unresponsive or exits unexpectedly. A failure in the live runtime kernel initialization is likely. First Action: Investigate src/boot.py, the entry point for the Sovereign-Loop kernel.

learn

Symptom Potential Cause & First Action
The learning session fails to initialize. The command cannot instantiate the required autonomous agents. First Action: Immediately inspect src/agents/ for errors in the Professor or Alpha agent definitions. These are the most common points of failure for this command.
A learning cycle runs but produces errors or non-deterministic behavior. This points to a logical error within an agent's cognitive or operational code. First Action: Review the agent source code in src/agents/ for bugs.

test

Symptom Potential Cause & First Action
The test suite reports one or more failures. This is a clear indicator of a system integrity failure. First Action: Analyze the pytest output to identify the specific module or function that failed. This pinpoints the location of the bug.
The test command itself fails to run. The test runner or its configuration is broken. First Action: Check the tests/ directory and pytest.ini for configuration errors.

clean

Symptom Potential Cause & First Action
Command fails with permission errors. The script cannot delete temporary files or artifacts. First Action: Check file and directory permissions in the project folder.
System exhibits persistent state-related issues despite restarts. Stale or corrupted artifacts from a previous run are interfering with the current session. First Action: Run python manage.py clean to ensure a clean operational state.

If the CLI commands execute without error but the system remains non-operational, the failure lies deeper within the core components.

3.0 Core System Component Diagnostics

Effective troubleshooting requires a clear understanding of the system's core architecture. ASI-OS operates on a dual-architecture model, separating a live runtime kernel from an offline cognitive ecosystem. This section focuses on diagnosing the live components responsible for real-time operations.

3.1 Sovereign-Loop Kernel Failures

The Sovereign-Loop is the live runtime kernel. If the server starts but is unresponsive, or if the process terminates shortly after launch with a critical error, suspect a kernel failure. The entire system is non-operational if this component fails.

3.2 Safety Governor (src/core/safety_governor.py) Malfunctions

This module enforces hardware and cognitive guardrails. A malfunction is a high-severity issue. Symptoms of a Safety Governor malfunction include:

  • The system taking actions that violate defined constraints (e.g., excessive resource consumption).
  • Autonomous agents operating outside of their prescribed behavioral limits.
  • A lack of error logging when a safety boundary is breached.

Diagnostic Action: Check the audit trails in the data/ledger/ directory. These logs provide full traceability of all autonomous actions and should contain evidence of governor engagement or failure.

3.3 Configuration Errors (configs/)

Malformed files in the configs/ directory can cause immediate startup failures or non-deterministic behavior. Any issue appearing after a recent configuration change is a likely configuration error.

Diagnostic Action: Verify all files within the configs/ directory for correct syntax, valid parameter values, and dependencies.

Having examined the core system, we now turn to issues arising from user-added extensions.

4.0 Diagnosing Failures in Custom Extensibility Modules

System extensibility is a core feature but also a common failure domain. This section provides a systematic approach to isolating failures within user-added Skills and Agents.

4.1 Troubleshooting Custom Skills (src/skills/)

The system loader automatically discovers and registers capabilities from the src/skills/ directory. If a new skill is unavailable or causes instability, follow these steps.

  1. Verify File Placement: Confirm the new skill's Python file is in the src/skills/ directory.
  2. Check for Code Errors: Isolate the new skill file and check for syntax errors or missing dependencies not included in the core installation.
  3. Review System Logs: On startup, review system logs for messages indicating a failure to load or register the new skill.

4.2 Troubleshooting Custom Agents (src/agents/)

New agent behaviors are defined by adding files to the src/agents/ directory. Failures related to custom agents typically manifest during learning cycles or agent invocation.

  1. Verify File Placement: Ensure the new agent definition file is in the src/agents/ directory.
  2. Check Agent Definition Logic: Scrutinize the agent's code for logical errors, incorrect state management, or flawed interaction protocols.
  3. Isolate and Test: Isolate the agent; disable others to rule out emergent, multi-agent conflicts.

Once specific module debugging has been exhausted, use the system's built-in advanced diagnostic tools for a more comprehensive analysis.

5.0 Advanced Diagnostics and Data Integrity Verification

When initial troubleshooting does not reveal the root cause, leverage the system's built-in tools for a deeper integrity analysis. The test suite and audit trails are the primary tools for uncovering hidden bugs or data corruption.

5.1 Leveraging the Test Suite for Deep Diagnosis

The test suite is your most powerful tool for verifying core system integrity. Execute the entire suite with: python manage.py test

The pytest output pinpoints the exact module, function, and assertion that failed. Use this to guide your debugging effort with precision, focusing directly on the component with a confirmed failure.

5.2 Analyzing Audit Trails for Full Traceability

All autonomous actions are logged as immutable audit trails in the data/ledger/ directory. Use these logs to reconstruct system behavior leading up to a failure. Look for:

  • Explicit Error Messages: Stack traces or errors that directly identify the problem.
  • Anomalous Action Sequences: Deviations from expected behavior that indicate a logical flaw in an agent or skill.
  • Missing Log Entries: An absence of logs where an action was expected, indicating a component failed to trigger or execute.

This concludes the diagnostic phase. The final step is to follow a structured protocol for service restoration.

6.0 Service Restoration Checklist

After diagnosing a problem, a systematic approach is required to restore the system to a known-good operational state. The following checklist synthesizes key recovery actions into a repeatable protocol.

System Restoration Protocol

  1. Isolate Customizations: Temporarily move any custom skills or agents out of src/skills/ and src/agents/ to a backup location.
  2. Clean System Artifacts: Run python manage.py clean to remove temporary files or cached data from previous sessions.
  3. Verify Configuration: Manually inspect all files in the configs/ directory to ensure they are syntactically correct and contain the intended parameters.
  4. Re-install Dependencies: Run pip install -r requirements.lock to ensure the environment has the exact versions of all required dependencies.
  5. Run Full Test Suite: Execute python manage.py test. A fully passing test suite confirms core system integrity. Do not proceed if tests are failing.
  6. Attempt Kernel Restart: Start the server in its primary operational mode with python manage.py server --mode Sovereign-Loop and monitor the console for startup errors.

Clone this wiki locally