dss/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for DSS (Design System Server).

Table of Contents

• Installation Issues
• Server Issues
• Figma Integration Issues
• Token Ingestion Issues
• Test Failures
• Performance Issues
• Database Issues

Installation Issues

Python Version Error

Problem: Python 3.10+ is required

Solution:

# Check your Python version
python3 --version

# Install Python 3.10+ if needed (Ubuntu/Debian)
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip

# Or use pyenv
pyenv install 3.10.0
pyenv local 3.10.0

pip Install Fails

Problem: error: externally-managed-environment

Solution:

# Use virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Or use --break-system-packages (not recommended)
pip install --break-system-packages -r requirements.txt

Permission Denied on setup.sh

Problem: Permission denied: ./setup.sh

Solution:

chmod +x setup.sh
./setup.sh

Server Issues

Port Already in Use

Problem: Address already in use: 3456

Solution:

# Find process using port 3456
lsof -i :3456

# Kill the process
kill -9 <PID>

# Or use different port
PORT=3457 python -m tools.api.server

ModuleNotFoundError

Problem: ModuleNotFoundError: No module named 'tools'

Solution:

# Ensure you're in project root
cd /path/to/dss

# Activate virtual environment
source .venv/bin/activate

# Verify Python path
python3 -c "import sys; print(sys.path)"

# Run from project root
python3 -m tools.api.server

Server Starts But Can't Connect

Problem: Server starts but curl http://localhost:3456/status fails

Solution:

# Check server is actually running
ps aux | grep "tools.api.server"

# Check logs for errors
tail -f .dss/logs/server.log

# Verify port binding
netstat -tulpn | grep 3456

# Try 127.0.0.1 instead of localhost
curl http://127.0.0.1:3456/status

Figma Integration Issues

Figma API Returns Empty

Problem: extract_variables() returns 0 tokens

Possible Causes & Solutions:

1. No Variables in File

   # Check if file has Variables (requires Figma Pro/Org)
   # Variables are different from Styles
   

2. Wrong File Key

   # Get file key from URL:
   # https://figma.com/file/FILE_KEY/...
   # Use FILE_KEY, not the file name
   

3. Invalid Token

   # Verify token is valid
   curl -H "X-Figma-Token: $FIGMA_TOKEN" \
        https://api.figma.com/v1/me
   
   # Should return your user info
   

4. Use Styles Instead

   # For community files, use styles
   result = await suite.extract_styles(file_key)
   

Figma API Rate Limiting

Problem: 429 Too Many Requests

Solution:

# Increase cache TTL
export FIGMA_CACHE_TTL=600  # 10 minutes

# Add delay between requests
import asyncio
await asyncio.sleep(1)

Figma Token Not Found

Problem: FigmaToken environment variable not set

Solution:

# Add to .env file
echo "FIGMA_TOKEN=figd_your_token_here" >> .env

# Or export directly
export FIGMA_TOKEN=figd_your_token_here

# Verify
echo $FIGMA_TOKEN

Token Ingestion Issues

Tailwind Parser Returns 0 Tokens

Problem: Tailwind config parsed but no tokens extracted

Known Issue: Regex doesn't match all config formats

Workaround:

# Use JSON tokens instead
import json
from tools.ingest.json_tokens import JSONTokenSource

# Convert Tailwind to JSON format
tokens_json = {
    "color": {
        "primary": {"value": "#3B82F6", "type": "color"}
    }
}

parser = JSONTokenSource()
result = await parser.extract(json.dumps(tokens_json))

CSS Variables Not Extracted

Problem: CSS parsed but tokens not found

Solution:

# Ensure using :root selector
css_content = """
:root {
    --color-primary: #3B82F6;  /* This works */
}

.class {
    --local-var: red;  /* This doesn't work (scoped) */
}
"""

SCSS Import Errors

Problem: @import statements cause parsing errors

Solution:

# DSS doesn't resolve @import
# Extract the compiled CSS instead, or inline variables

Test Failures

Async Tests Skipped

Problem: All @pytest.mark.asyncio tests skipped

Solution:

# Install pytest-asyncio
pip install pytest-asyncio

# Verify installation
pytest --version
# Should show: plugins: asyncio-...

# Run tests again
pytest tests/

Tests Fail: "database is locked"

Problem: SQLite database locked during tests

Solution:

# Use separate test database
export TEST_DB_PATH=.dss/test.db

# Or delete lock file
rm -f .dss/dss.db-lock

# Run tests
pytest

Import Errors in Tests

Problem: ModuleNotFoundError in test files

Solution:

# Run from project root
cd /path/to/dss

# Verify pytest.ini exists and has:
# pythonpath = .

# Run with python path
PYTHONPATH=. pytest tests/

Performance Issues

Slow File Scanning

Problem: Project scan takes >10 seconds

Solution:

# Add more directories to skip
scanner = ProjectScanner(
    path=".",
    exclude=['node_modules', '.git', 'dist', 'build', '.venv']
)

# Use cache
scanner = ProjectScanner(path=".", use_cache=True)

# Scan specific subdirectories only
scanner = ProjectScanner(path="./src")

High Memory Usage

Problem: Python process using >1GB RAM

Solution:

# Process tokens in batches
for batch in batches(tokens, 1000):
    process_batch(batch)

# Clear collections after use
collection.tokens.clear()

# Use generators for large datasets
def token_generator():
    for token in large_dataset:
        yield process(token)

Slow Figma API Calls

Problem: Figma extraction takes >30 seconds

Solution:

# Check network latency
ping api.figma.com

# Use local JSON export for development
figma export --format json

# Increase cache TTL
export FIGMA_CACHE_TTL=3600  # 1 hour

Database Issues

Database Corruption

Problem: database disk image is malformed

Solution:

# Backup database
cp .dss/dss.db .dss/dss.db.backup

# Try to repair
sqlite3 .dss/dss.db "PRAGMA integrity_check;"

# If corrupt, restore from backup or delete
rm .dss/dss.db
# Database will be recreated on next run

Can't Write to Database

Problem: attempt to write a readonly database

Solution:

# Check permissions
ls -l .dss/dss.db

# Fix permissions
chmod 644 .dss/dss.db
chown $USER:$USER .dss/dss.db

# Check parent directory is writable
ls -ld .dss/
chmod 755 .dss/

Getting Help

Check Logs

# Server logs
tail -f .dss/logs/server.log

# MCP server logs
tail -f .dss/logs/mcp.log

# Application logs
python -m tools.api.server --log-level DEBUG

Debug Mode

# Enable debug logging
export LOG_LEVEL=DEBUG

# Run with verbose output
python -m tools.api.server -vv

Still Stuck?

1. Search Issues: https://github.com/your-org/dss/issues
2. Open Issue: Provide:
   • DSS version (git describe --tags)
   • Python version (python3 --version)
   • Operating system
   • Full error message
   • Steps to reproduce
3. Check Documentation:
   • README.md
   • QUICKSTART.md
   • ARCHITECTURE.md
   • CODE_QUALITY.md

Common Error Messages

"RuntimeError: Event loop is closed"

Solution:

# Use asyncio.run() for top-level async calls
import asyncio

async def main():
    result = await some_async_function()

if __name__ == "__main__":
    asyncio.run(main())

"JSONDecodeError: Expecting value"

Solution:

# Check JSON is valid
import json

try:
    data = json.loads(content)
except json.JSONDecodeError as e:
    print(f"Invalid JSON: {e}")
    print(f"Content: {content[:100]}")

"ConnectionRefusedError: [Errno 111]"

Solution:

# Server not running - start it
python -m tools.api.server

# Or check correct host/port
curl http://127.0.0.1:3456/status

Prevention Tips

1. Always use virtual environment
2. Run tests before committing
3. Keep dependencies updated
4. Check logs regularly
5. Use .env for configuration
6. Back up database periodically

---

Can't find your issue? Open a GitHub issue with details!