Troubleshooting#

Common issues and their solutions when working with Jac.

Installation Issues#

ModuleNotFoundError: No module named 'jaclang'#

Cause: Jac is not installed in your current Python environment.

Solution:

pip install jaseci

If using a virtual environment, make sure it's activated:

source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

Plugin not found: byllm / jac-client / jac-scale#

Cause: Plugin not installed or not enabled.

Solution:

# Install the plugin
pip install byllm        # For AI features
pip install jac-client   # For full-stack
pip install jac-scale    # For production deployment

# Or install all at once
pip install jaseci

Command 'jac' not found#

Cause: Jac CLI not in PATH or not installed.

Solution:

# Verify installation
pip show jaclang

# If installed but not in PATH, use python -m
python -m jaclang run myfile.jac

Syntax Errors#

Unexpected token 'entry' / Missing handler#

Error:

Walker did not execute any abilities

Cause: Walker spawned at root but missing with \root entry` handler.

Wrong:

walker Greeter {
    can greet with Person entry {
        print(f"Hello, {here.name}!");
    }
}

with entry {
    root spawn Greeter();  # Nothing happens!
}

Fix: Add a root entry handler:

walker Greeter {
    can start with `root entry {
        visit [-->];  # Start visiting connected nodes
    }

    can greet with Person entry {
        print(f"Hello, {here.name}!");
        visit [-->];  # Continue to next nodes
    }
}

Cannot assign: missing 'glob' keyword#

Error:

Cannot assign to variable without 'glob' keyword in client context

Cause: Global variable assignment in cl {} block requires glob.

Wrong:

cl {
    AuthContext = createContext(None);  # Error!
}

Fix:

cl {
    glob AuthContext = createContext(None);  # Correct
}

Enumerate unpacking syntax#

Error:

Unexpected token 'i'

Cause: Enumerate unpacking needs parentheses.

Wrong:

for i, name in enumerate(names) {
    print(f"{i}: {name}");
}

Fix:

def example() {
    names = ["Alice", "Bob", "Charlie"];
    for (i, name) in enumerate(names) {
        print(f"{i}: {name}");
    }
}

Non-default argument follows default argument#

Error:

Non-default argument 'created_at' follows default argument 'completed'

Cause: Node/object attributes with defaults must come after required attributes.

Wrong:

node Task {
    has title: str;
    has completed: bool = False;
    has created_at: str;  # Error: non-default after default
}

Fix:

node Task {
    has title: str;
    has created_at: str;           # Required first
    has completed: bool = False;   # Defaults last
}

Type name conflicts with Python builtin#

Error:

'any' shadows built-in name

Cause: Using a type name that conflicts with Python builtins like any, all, list, etc.

Fix: Use a different variable name or explicit type:

obj Example {
    # Instead of: has value: any;
    has value: object;  # Or a specific type
}

Runtime Errors#

Walker reports are empty#

Cause: Walker didn't visit any nodes or didn't call report.

Debug steps:

Verify nodes are connected to root:

with entry {
    print(f"Nodes connected to root: {len([-->])}");
}

Add debug prints in walker:

walker Debug {
    can start with `root entry {
        print("At root");
        print(f"Connected: {[-->]}");
        visit [-->];
    }

    can process with entry {
        print(f"Visiting: {here}");
    }
}

Ensure report is called:

can find with Person entry {
    print(f"Found: {here.name}");
    report here;  # Don't forget this!
    visit [-->];
}

Graph query returns empty list#

Cause: No nodes match the query filter.

Debug:

with entry {
    # Check all connections (no filter)
    all_nodes = [-->];
    print(f"All connected: {len(all_nodes)}");

    # Check with filter
    people = [-->](`?Person);
    print(f"People: {len(people)}");
}

Common issues:

Nodes not connected to the right parent
Type filter doesn't match (check spelling)
Using wrong direction ([-->] vs [<--])

AttributeError: 'NoneType' has no attribute#

Cause: Trying to access attributes on a None value.

Debug:

can process with entry {
    if here is not None {
        print(here.name);
    } else {
        print("here is None!");
    }
}

Full-Stack Issues#

Server won't start: Address already in use#

Cause: Port 8000 (default) is already in use.

Solution:

# Use a different port
jac start main.jac --port 8001

# Or find and kill the process using the port
lsof -i :8000  # Linux/Mac
netstat -ano | findstr :8000  # Windows

Frontend not updating after changes#

Cause: Hot Module Replacement (HMR) not working or cache issue.

Solutions:

Ensure you're using --dev flag:

jac start main.jac --dev

Hard refresh the browser: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
Clear browser cache and restart server

API endpoint returns 401 Unauthorized#

Cause: Walker requires authentication but request has no token.

Solutions:

Make walker public for testing:

walker:pub my_walker {  # Add :pub modifier
    # ...
}

Or include auth token in request:

curl -X POST http://localhost:8000/walker/my_walker \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

CORS error in browser console#

Cause: Frontend and backend on different origins.

Solution: Configure CORS in jac.toml:

[plugins.scale.cors]
allow_origins = ["http://localhost:5173", "http://localhost:3000"]
allow_methods = ["GET", "POST", "PUT", "DELETE"]
allow_headers = ["*"]

useWalker returns undefined#

Cause: Walker response not being accessed correctly.

Debug:

cl {
    def MyComponent() {
        result = useWalker(my_walker, {});

        # Check the full response
        console.log("Result:", result);
        console.log("Reports:", result?.reports);

        # Access reports array
        if result and result.reports {
            for item in result.reports {
                print(item);
            }
        }
    }
}

See Walker Responses for details on the response structure.

AI Integration Issues#

OpenAI API key not found#

Error:

AuthenticationError: No API key provided

Solution:

# Set environment variable
export OPENAI_API_KEY="sk-..."

# Or in .env file
echo "OPENAI_API_KEY=sk-..." > .env
source .env

Rate limit exceeded#

Error:

RateLimitError: Rate limit reached

Solutions:

Add delays between requests
Use a smaller/cheaper model for testing:

glob llm = Model(model_name="gpt-4o-mini");  # Cheaper than gpt-4

Implement caching for repeated queries

Model not responding / timeout#

Cause: Network issues or model overloaded.

Solutions:

Check your internet connection
Verify API key is valid
Try a different model:

# Try different providers
glob llm = Model(model_name="claude-3-haiku");  # Anthropic
glob llm = Model(model_name="gpt-4o-mini");     # OpenAI

LLM returns unexpected format#

Cause: Model not following the expected output structure.

Solution: Use structured outputs with type hints:

"""Extract person info from text."""
def extract_person(text: str) -> PersonInfo by llm();

obj PersonInfo {
    has name: str;
    has age: int;
    has occupation: str;
}

See Structured Outputs for more details.

Getting More Help#

Debug Mode#

Run with debug output:

jac run myfile.jac --verbose

Check Syntax#

Validate code without running:

jac check myfile.jac

Community Resources#

Discord: Join the Jac community
GitHub Issues: Report bugs
JacGPT: Ask questions

Quick Reference: Common Fixes#

Error	Quick Fix
Walker doesn't run	Add `can start with \`root entry { visit [-->]; }`
Missing glob keyword	Use `glob var = value;` in `cl {}` blocks
Enumerate unpacking	Use `for (i, x) in enumerate(...)`
Attribute order	Put required attributes before defaults
Empty reports	Check node connections and `report` calls
401 Unauthorized	Add `:pub` modifier to walker or include auth token
CORS error	Configure `[plugins.scale.cors]` in jac.toml
API key missing	Set `OPENAI_API_KEY` environment variable