Troubleshooting

Troubleshooting

Julia Server Issues

• Julia server fails to start: Make sure Julia 1.10+ is installed correctly and all required packages are installed. Run cd julia && julia -e 'using Pkg; Pkg.activate("."); Pkg.instantiate()' to install all required packages.

• Connection refused errors: Ensure the Julia server is running on port 8052. Check with curl http://localhost:8052/api/v1/health to see if the server is responding.

• Package errors: If you encounter package-related errors, try updating your Julia packages with cd julia && julia -e 'using Pkg; Pkg.activate("."); Pkg.update()'.

• Module loading errors: If you encounter module loading errors, ensure that all modules are properly imported with the correct relative paths. The restructured backend uses a modular architecture with clear separation of concerns.

• Configuration errors: Make sure your environment variables are properly set in the .env file. The server will use default values for missing configurations, but some features may be limited.

• RPC URL errors: If you see errors like "invalid project id" or "unauthorized" when connecting to blockchain networks, check your RPC URLs in the configuration. Make sure you're using valid API keys from providers like Infura or Alchemy. For testing, you can use public RPC endpoints, but they may have rate limits or reliability issues.

• Precompilation issues: If you encounter precompilation errors, try clearing the Julia compilation cache with julia -e 'using Pkg; Pkg.precompile()' and then restart the server.

Python Wrapper Issues

• Installation errors: If you encounter ERROR: No matching distribution found for juliaos or GitHub URL errors, use the correct installation format:

  # Correct format
  pip install git+https://github.com/Juliaoscode/JuliaOS.git#subdirectory=packages/python-wrapper
  
  # For extras, use quotes around the URL
  pip install "git+https://github.com/Juliaoscode/JuliaOS.git#subdirectory=packages/python-wrapper[llm]"

  • No matching distribution found for juliaos: This error means you tried pip install juliaos. This package is not on PyPI. You must install from GitHub or use the local development setup as shown in the Installation section.

  • git clone ... did not run successfully (Exit Code 128) when installing from GitHub:

    • Check the URL: Ensure you are using the exact format: git+https://github.com/Juliaoscode/JuliaOS.git#subdirectory=packages/python-wrapper. Do not use URLs copied from the browser address bar that might contain /tree/.

    • Check Git: Make sure git is installed correctly and available in your system's PATH.

    • Check Network/Permissions: Ensure you have network connectivity to GitHub. For private repositories (not applicable here), SSH keys or tokens might be needed.

    • Use Quotes: Try putting quotes around the full URL in your pip install command, especially if installing extras: pip install "git+https://...[llm]".

    • Use Local Install: If problems persist, clone the repository first and use the development install method: cd JuliaOS/packages/python-wrapper && pip install -e ..

• Import errors: After installation, verify the package is installed correctly with pip list | grep juliaos. If it's not listed, try reinstalling with the GitHub URL method above.

  • Import errors (ModuleNotFoundError: No module named 'juliaos'): After installation, verify the package is installed correctly in your current Python environment (pip show juliaos or pip list | grep juliaos). If using a virtual environment, ensure it's activated. If it's not listed, try reinstalling using the recommended methods.

• Connection errors: Make sure the Julia server is running before using the Python wrapper. The wrapper connects to the server via HTTP on port 8052.

• Async errors: The Python wrapper uses asyncio for asynchronous operations. Make sure you're using await with async functions and running them within an async context (e.g., asyncio.run()).

CLI Issues

• Command not found: Ensure you're running the CLI from the project root directory with node packages/cli/interactive.cjs.

• Connection errors: Make sure the Julia server is running before starting the CLI. The CLI connects to the server via HTTP on port 8052.

• Menu navigation errors: If you encounter issues navigating the CLI menu, try restarting the CLI. Some menu options may depend on the server state.

• Missing dependencies: If you encounter errors about missing modules, run npm install to ensure all Node.js dependencies are installed.

• Server not responding: If the Julia server is not responding, you can use the mock server instead: node packages/cli/mock_server.js.

• Server port conflicts: If port 8052 is already in use, you can modify the port in the server configuration or kill the process using that port.

• Check server status: You can check if the server is running with curl http://localhost:8052/api/v1/health.

Docker Issues

• Build failures: If the Docker build fails, check your Docker installation and ensure you have sufficient disk space. You can also try building with the --no-cache option: docker compose build --no-cache.

• Container fails to start: Check the logs with docker compose logs juliaos-server to see what's causing the issue. Common issues include port conflicts or missing environment variables.

• Port conflicts: If port 8052 is already in use, modify the port mapping in docker-compose.yml to use a different port: "8053:8052" would map the container's port 8052 to your host's port 8053.

• Helper script issues: If the scripts/run-docker.sh script doesn't work, ensure it's executable (chmod +x scripts/run-docker.sh) and try running the Docker commands directly as shown in the Docker Compose section.

• Environment variable issues: If you're having trouble with environment variables, make sure your .env file is in the project root and contains the correct format. You can also pass environment variables directly to Docker: docker compose run -e OPENAI_API_KEY=your_key juliaos-cli.

• Docker Compose version: Make sure you're using Docker Compose V2, which uses the docker compose command (without the hyphen) instead of docker-compose.