troubleshooting.md

Troubleshooting Guide

This guide helps you resolve common issues when working with the NEAR Swarm Intelligence framework.

Installation Issues

Python Version Error

Problem: Error about Python version compatibility.

Solution:

1. Check your Python version:

python --version

2. Install Python 3.12+:

# macOS
brew install [email protected]

# Ubuntu
sudo apt update
sudo apt install python3.12

Package Dependencies

Problem: Missing dependencies or version conflicts.

Solution:

1. Update pip:

python -m pip install --upgrade pip

2. Install in development mode:

pip install -e .

Plugin Issues

Plugin Loading Errors

Problem: "Plugin not found" or loading errors.

Solution:

1. Check plugin structure:

my-agent/
├── __init__.py
├── agent.yaml     # Must exist
├── plugin.py      # Must exist
└── README.md

2. Verify plugin is installed:

near-swarm plugins list

3. Try reinstalling:

near-swarm plugins remove my-agent
near-swarm plugins install ./my-agent

Plugin Configuration

Problem: Invalid plugin configuration.

Solution:

1. Validate configuration:

near-swarm config validate

2. Check YAML syntax:

# agent.yaml
name: my-agent
description: "Agent description"
version: "0.1.0"
author: "Your Name"

capabilities:
  - capability_one
  - capability_two

llm:
  provider: ${LLM_PROVIDER}
  model: ${LLM_MODEL}
  temperature: 0.7

near:
  network: ${NEAR_NETWORK:-testnet}
  account_id: ${NEAR_ACCOUNT_ID}
  private_key: ${NEAR_PRIVATE_KEY}

3. Debug configuration loading:

near-swarm config show --debug

Plugin Lifecycle

Problem: Plugin initialization or cleanup failures.

Solution:

1. Implement proper lifecycle methods:

class MyPlugin(AgentPlugin):
    async def initialize(self) -> None:
        try:
            # Initialize resources
            self.llm = self.create_llm_provider(self.config.llm)
            self.near = await self.create_near_connection(self.config.near)
        except Exception as e:
            self.logger.error(f"Initialization failed: {e}")
            raise PluginError(str(e))
    
    async def cleanup(self) -> None:
        try:
            # Clean up resources
            await self.near.close()
        except Exception as e:
            self.logger.error(f"Cleanup failed: {e}")

2. Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Configuration Issues

Environment Variables

Problem: "Environment variable not set" errors.

Solution:

1. Check .env file exists:

ls -la .env

2. Verify required variables:

# Required: NEAR account details
NEAR_NETWORK=testnet
NEAR_ACCOUNT_ID=your-account.testnet
NEAR_PRIVATE_KEY=your-private-key

# Required: AI provider details
LLM_PROVIDER=hyperbolic
LLM_API_KEY=your-llm-api-key

# Optional: AI model settings
LLM_MODEL=deepseek-ai/DeepSeek-V3

3. Load variables:

source .env

Configuration Validation

Problem: Configuration validation errors.

Solution:

1. Use configuration models:

from pydantic import BaseModel, Field

class MyConfig(BaseModel):
    name: str
    version: str = Field(pattern=r"^\d+\.\d+\.\d+$")
    temperature: float = Field(ge=0, le=1)

2. Validate during loading:

from near_swarm.config import ConfigurationManager

config_manager = ConfigurationManager()
try:
    config = config_manager.load_config("my-agent", MyConfig)
except ConfigError as e:
    print(f"Configuration error: {e}")

Runtime Issues

LLM Integration

Problem: LLM API errors or unexpected responses.

Solution:

1. Verify API key:

from near_swarm.llm import LLMProvider

provider = LLMProvider(config.llm)
try:
    await provider.validate_connection()
except LLMError as e:
    print(f"LLM error: {e}")

2. Handle API errors:

async def safe_llm_call(self, prompt: str) -> Dict[str, Any]:
    try:
        return await self.llm.query(prompt)
    except LLMError as e:
        self.logger.error(f"LLM call failed: {e}")
        return {"error": str(e)}

NEAR Integration

Problem: NEAR blockchain interaction errors.

Solution:

1. Test connection:

from near_swarm.near import NEARConnection

near = NEARConnection(config.near)
try:
    await near.validate_connection()
except NEARError as e:
    print(f"NEAR error: {e}")

2. Handle transaction errors:

async def safe_transfer(self, recipient: str, amount: str) -> Dict[str, Any]:
    try:
        return await self.near.send_tokens(recipient, amount)
    except NEARError as e:
        self.logger.error(f"Transfer failed: {e}")
        return {"error": str(e)}

Transaction Issues

Nonce Errors

• Issue: Transaction failed: nonce too low
  • Cause: Multiple transactions sent in rapid succession
  • Solution: The framework automatically handles retries with exponential backoff
  • Verification: Check transaction status in explorer URL provided in logs

Transaction Not Executing

• Issue: Agent analyzes but doesn't execute transactions
  • Cause: Confidence threshold not met (requires >75%)
  • Solution: This is normal behavior. The agent is being conservative
  • Verification: Check confidence level in logs

Transaction Status

• Issue: Unclear if transaction was successful
  • Solution: Check the logs for:

    ✅ Transaction Successfully Executed!
    • Transaction Hash: <hash>
    • Explorer URL: <url>
    

  • Verification: Visit the explorer URL to confirm status

Common Transaction Errors

Error	Cause	Solution
nonce too low	Transaction ordering issue	Automatic retry handles this
insufficient funds	Account balance too low	Add funds to account
gas price too low	Network congestion	Automatic retry with backoff

Common Error Messages

"Plugin directory not found"

Solution:

1. Check directory structure:

ls -R my-agent/

2. Create plugin with CLI:

near-swarm create agent my-agent

"Invalid plugin configuration"

Solution:

1. Validate YAML syntax
2. Check variable substitution
3. Run validation:

near-swarm config validate my-agent

"Plugin initialization failed"

Solution:

1. Check resource initialization
2. Verify dependencies
3. Enable debug mode:

near-swarm start my-agent --debug

Getting Help

1. Check documentation:

   • Tutorial
   • Core Concepts
   • API Reference

2. Search issues:

   • GitHub Issues

3. Join community:

   • Discord
   • Forum

4. Debug tools:

# Enable debug logging
import logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)