Skip to content

Troubleshooting

Common issues and solutions when using TofuSoup.

Installation Issues

Command not found: soup

Symptom: soup: command not found after installation

Solutions: 1. Verify installation: 

pip list | grep tofusoup

  1. Check Python bin is in PATH: 

    python -m pip show tofusoup
which soup

  2. Try running via Python module: 

    python -m tofusoup.cli --help

  3. Add Python bin to PATH (macOS/Linux): 

    export PATH="$HOME/.local/bin:$PATH"

Module import errors

Symptom: ModuleNotFoundError when running soup

Solution: 

# For development installations
cd /path/to/tofusoup
uv sync

# For pip installations
pip install --upgrade tofusoup[all]

Harness Issues

Go harness build failures

Symptom: soup harness build fails

Solutions: 1. Check Go installation: 

go version  # Should be 1.21+

  1. Check GOPATH: 

    go env GOPATH

  2. Try building manually: 

    cd src/tofusoup/harness/go/soup-go
go build -o ../../../../harnesses/bin/soup-go

  3. Check for Go module issues: 

    go mod tidy
go mod verify

Harness binary not found

Symptom: No such file or directory: 'harnesses/bin/soup-go'

Cause: The harnesses/bin/ directory is a build artifact and not included in version control.

Solution: 

# Build harnesses (this creates the directory)
soup harness build --all

# Verify
ls harnesses/bin/
./harnesses/bin/soup-go --version

Note: You must build harnesses after cloning the repository or when switching branches that update harness code.

Harness CLI verification fails

Symptom: soup harness verify-cli fails

Solution: 

# Rebuild the harness
soup harness build soup-go

# Verify it runs
./harnesses/bin/soup-go --version

# Check logs
soup harness verify-cli soup-go --verbose

Test Failures

RPC connection timeouts

Symptom: Tests fail with "Connection timeout after 30s"

Causes & Solutions:

  1. Go server not starting: 

    # Check server logs
cat /tmp/tofusoup_plugin_debug.log

# Try starting server manually
soup rpc server-start

  2. Firewall blocking:

  3. Check firewall settings
  4. Allow Python and Go executables

  5. Test on localhost without firewall

  6. Port already in use: 

    # Check for processes using gRPC ports
lsof -i :50051

Wire protocol binary mismatches

Symptom: "Binary mismatch for test 'X'"

This is a real compatibility issue! It means Python and Go are producing different binary output.

Debug steps: 1. View the specific test: 

pytest conformance/wire/souptest_wire_python_vs_go.py::test_X -vv

  1. Compare binary outputs: 

    # See wire protocol guide for debugging
soup wire encode input.json python.out
./harnesses/bin/soup-go wire encode input.json go.out
diff <(xxd python.out) <(xxd go.out)

  2. Report the issue on GitHub with test details

CTY type errors

Symptom: 'UnrefinedUnknownValue' object is not subscriptable

Solution: This is a known issue with unknown values. Update pyvider-cty: 

pip install --upgrade pyvider-cty

Performance Issues

Tests running slowly

Solutions: 1. Run tests in parallel: 

pytest -n auto

  1. Run specific test suites: 

    soup test cty  # Instead of 'soup test all'

  2. Skip slow tests: 

    pytest -m "not slow"

Harness build taking too long

Solution: 

# Use cached builds
soup harness build --cache

# Build only what's needed
soup harness build soup-go  # Instead of --all

Configuration Issues

soup.toml not found

Symptom: "Configuration not loaded" warnings

Solution: TofuSoup searches for soup.toml in: 1. Path specified by --config-file 2. Current directory (./soup.toml)

Create one if needed: 

cat > soup.toml <<EOF
[global_settings]
default_python_log_level = "INFO"
EOF

Invalid configuration

Symptom: TofuSoupConfigError

Solution: 

# Validate syntax
python -c "import tomllib; tomllib.load(open('soup.toml', 'rb'))"

# Check configuration
soup config show

Matrix Testing Issues

Matrix testing not available

Symptom: Error: Matrix testing requires the 'wrknv' package

Cause: Matrix testing is an optional feature that requires wrknv.

Solution: 

# Install wrknv from local source (not yet on PyPI)
pip install -e /path/to/wrknv

# Or if published to PyPI
pip install wrknv

Note: Regular soup stir (without --matrix) works without this dependency.

stir command not finding tests

Symptom: "No tests found"

Solutions: 1. Check directory structure: 

ls -la tests/

  1. Verify test files have main.tf: 

    find tests/ -name "main.tf"

  2. Use correct path: 

    soup stir tests/  # Not just 'tests'

Matrix versions not working

Symptom: Tests only run against one version

Solution: Configure matrix in soup.toml: 

[workenv.matrix.versions]
terraform = ["1.5.7", "1.6.0"]
tofu = ["1.8.0"]

Then use --matrix flag: 

soup stir tests/ --matrix

Getting More Help

Enable debug logging

# CLI debug mode
soup --log-level DEBUG command

# Python logging
export TOFUSOUP_LOG_LEVEL=DEBUG
soup command

Check logs

# Plugin debug log
cat /tmp/tofusoup_plugin_debug.log

# Test output
soup/output/cli_verification/

Report Issues

If you can't resolve the issue:

  1. Check FAQ
  2. Search GitHub Issues
  3. Create a new issue with:
  4. TofuSoup version (soup --version)
  5. Python version (python --version)
  6. Go version (go version)
  7. Full error message
  8. Steps to reproduce

See Also