Troubleshooting

This page addresses common issues you may encounter when using FLE.

Common Issues

“No valid programs found for version X”

Symptom: You see this message during initialization.

Solution: This is normal during initialization. The system will start generating programs shortly. No action needed.

Database Connection Errors

Symptom: Errors connecting to the database when running evaluations.

Solution:

Verify your database configuration in the .env file
Ensure the database exists
For SQLite: Check that the directory for the database file exists
For PostgreSQL: Verify the database server is running

API Key Errors

Symptom: Authentication errors when running agent evaluations.

Solution:

Run the API key setup script:

python fle/eval/infra/setup_api_keys.py

Verify your API keys are correctly set in the .env file
Check that you’re using the correct provider (OpenAI, Anthropic, etc.)

Docker Issues

Symptom: Permission denied or Docker connection errors.

Solution:

Ensure Docker is installed and running
Verify your user has permission to run Docker without sudo:
```
sudo usermod -aG docker $USER
```
Log out and log back in for the group change to take effect
Test Docker access:
```
docker ps
```

Connection Issues

Symptom: Cannot connect to Factorio server.

Solution:

Make sure the Factorio server is running:
```
fle cluster start
```
Check that ports are properly configured
Verify Docker containers are running:
```
docker ps
```
Check Docker logs for errors:
```
docker logs <container_id>
```

Environment Creation Fails

Symptom: gym.make() fails with connection errors.

Solution:

Ensure Factorio containers are running
Check that the cluster setup is working
Verify network connectivity

No Environments Found

Symptom: list_available_environments() returns an empty list.

Solution:

Check that the task definitions directory exists
Verify JSON files in fle/eval/tasks/task_definitions/ are valid
Check file permissions
Ensure you’re running from the correct directory

Import Errors

Symptom: ModuleNotFoundError or import errors.

Solution:

Ensure you’re running from the correct directory

Check that all dependencies are installed:

pip install factorio-learning-environment[eval]

Verify the Python path includes the project root

Try reinstalling the package:

pip install --force-reinstall factorio-learning-environment

Space Age DLC Issues

Symptom: Factorio client is on version 2.x instead of 1.1.110.

Solution:

Open Steam library
Right-click Factorio → Properties
Navigate to DLC section
Uncheck Space Age DLC (this forces the 2.x branch)
Go to Betas tab
Select version 1.1.110

Testing Your Installation

Run the test suite to verify everything is working:

# Test the gym registry
python fle/env/tests/gym_env/test_registry.py

# List available environments
python fle/env/gym_env/example_usage.py --list

# Run with detailed output
python fle/env/gym_env/example_usage.py --detail

Getting Help

If you continue to experience issues:

Check the GitHub Issues
Join the Discord (#factorio-learning-env)
Review the Project Structure to understand the codebase layout

Debugging Tips

Enable Verbose Logging

Set environment variables for more detailed output:

export FLE_LOG_LEVEL=DEBUG

Check Docker Logs

View logs from Factorio containers:

# List running containers
docker ps

# View logs for a specific container
docker logs <container_id>

# Follow logs in real-time
docker logs -f <container_id>

Verify Environment Variables

Check that your .env file is properly loaded:

import os
from dotenv import load_dotenv

load_dotenv()
print(os.getenv('OPENAI_API_KEY'))  # Should show your API key (masked)
print(os.getenv('FLE_DB_TYPE'))     # Should show sqlite or postgres