Troubleshooting

Common issues and solutions when using Spry.

Installation Issues

Homebrew Installation Fails

Symptom

brew install reports tap not found or formula errors.

Solutions:

Update Homebrew:

brew update

Re-add the tap:

brew untap programmablemd/tap
brew tap programmablemd/tap
brew install spry

Check for conflicting installations:

which spry
brew list --versions spry

Binary Not Found After Installation

Symptom

spry: command not found after installation.

Solutions:

Verify installation location:

# Homebrew
ls $(brew --prefix)/bin/spry

# Manual install
ls ~/.local/bin/spry

Add to PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Reload shell:

source ~/.bashrc  # or ~/.zshrc

Deno Version Mismatch

Symptom

Errors about incompatible Deno version or missing APIs.

Solutions:

Check current version:

deno --version

Update Deno:

deno upgrade

Verify minimum version (2.5+):

deno --version | head -1
# Should show: deno 2.5.x or higher

Execution Errors

Task Not Found

Symptom

Error: Task 'task-name' not found

Causes and Solutions:

Typo in task ID:

# List available tasks
spry rb ls Spryfile.md

Task ID not in code fence meta:

Incorrect - no task ID:

```bash
echo "hello"
```

Correct - has task ID:

```bash my-task
echo "hello"
```

File not included:

# Check if file is being parsed
spry axiom ls Spryfile.md --verbose

Circular Dependency Detected

Symptom

Error: Cycle detected in task dependencies

Solution:

Visualize dependencies:

spry axiom projection Spryfile.md --pretty | jq '.edges'

Look for cycles like:

task-a depends on task-b
task-b depends on task-c
task-c depends on task-a  # Creates cycle

Fix by restructuring dependencies or removing one edge.

Shell Command Fails

Symptom

Task exits with non-zero code.

Solutions:

Run with verbose output:

spry rb run Spryfile.md --verbose rich

Check environment variables:

# Verify required variables are set
env | grep EXPECTED_VAR

Test command manually:

# Copy the command from code cell and run directly
bash -c 'your-command-here'

Permission Denied

Symptom

Permission denied when running tasks.

Solutions:

Check file permissions:

ls -la ./script.sh
chmod +x ./script.sh

Verify Deno permissions:

# Run with all permissions
deno run -A bin/spry.ts rb run Spryfile.md

Check directory write access:

ls -la ./output-directory/

SQLPage Issues

SQLPage Not Starting

Symptom

sqlpage command fails or port not accessible.

Solutions:

Check if SQLPage is installed:

which sqlpage
sqlpage --version

Verify port availability:

lsof -i :8080

Check configuration:

cat sqlpage.json

Database Connection Failed

SQLite Connection Error

Symptom

SQLPage can't connect to database.

Solutions:

Verify database file exists:

ls -la *.db

Check connection string:

{
"database_url": "sqlite://./data.db"
}

Test database directly:

sqlite3 ./data.db ".tables"

Connection refused (PostgreSQL)

Symptom

Cannot connect to PostgreSQL

Solutions:

# Verify PostgreSQL is running
pg_isready

# Check connection string
echo $DATABASE_URL

# Test connection manually
psql $DATABASE_URL

Migration failed

Symptom

Database schema migration errors

Solutions:

Check SQL syntax in schema files
Ensure migrations run in correct order
Verify database user has CREATE permissions
Try running migrations manually to see detailed errors

SQL Files Not Generated

Symptom

Expected .sql files missing after spry sp init.

Solutions:

Verify Spryfile has SQL cells:

spry axiom ls Spryfile.md | grep sql

Check output directory:

ls -la sqlpage/

Run with verbose output:

spry sp init Spryfile.md --verbose

Configuration Issues

Environment Variables Not Interpolated

Symptom

$\{env.VAR_NAME\} appears literally in output.

Solutions:

Check variable is exported:

export MY_VAR="value"
echo $MY_VAR

Verify frontmatter syntax (quotes required):

---
config:
  value: "${env.MY_VAR}"
---

Check for typos in variable name.

Frontmatter Parse Error

Symptom

YAML parsing errors in Spryfile.

Solutions:

Validate YAML syntax:

# Use online validator or test with Deno
deno eval "import * as yaml from 'yaml'; console.log(yaml.parse(Deno.readTextFileSync('Spryfile.md').split('---')[1]))"

Common issues:
- Missing quotes around special characters
- Incorrect indentation (use spaces, not tabs)
- Missing closing ---
Example correct frontmatter:

---
title: "My Spryfile"
config:
  key: "value with: special chars"
---

Import Resolution Failed

Symptom

Error: Could not resolve import

Solutions:

Verify imported file exists:

ls -la ./path/to/imported.md

Check import syntax:

Use relative paths:

@import ./shared/common.md

Absolute paths won't work:

@import /home/user/common.md

Check for circular imports.

Graph and Projection Issues

Empty Graph Output

Symptom

spry axiom projection returns empty or minimal data.

Solutions:

Check file has content:

wc -l Spryfile.md

Verify markdown structure:

spry axiom inspect Spryfile.md

Check for parsing errors:

spry axiom ls Spryfile.md --verbose

DOT Export Fails

Symptom

Graphviz export produces invalid DOT.

Solutions:

Export to JSON first:

spry axiom projection Spryfile.md --pretty > graph.json

Check for special characters in node labels.
Use simpler graph options:

spry axiom projection Spryfile.md --format dot --simple

Performance Issues

Slow Execution

Symptom

Tasks take longer than expected.

Solutions:

Check for unnecessary dependencies:

spry rb ls Spryfile.md
# Review dependency chains

Enable parallel execution:

spry rb run Spryfile.md --parallel

Profile slow tasks:

time spry rb run Spryfile.md task-name

High Memory Usage

Symptom

Process uses excessive memory.

Solutions:

Process large files in chunks.
Use streaming for data operations.
Check for memory leaks in custom scripts.

Debugging Tips

Enable Verbose Output

# Runbook verbose
spry rb run Spryfile.md --verbose rich

### Inspect AST

```bash
# View parsed structure
spry axiom inspect Spryfile.md

# Export full graph
spry axiom projection Spryfile.md --pretty > debug.json

Test Individual Tasks

# Run single task
spry rb run Spryfile.md specific-task

# Dry run to see plan
spry rb ls Spryfile.md

Getting More Help

Need Additional Support?

If these solutions don't resolve your issue, here's how to get help:

Check GitHub Issues - Search existing issues for similar problems
Open a New Issue - Include the following information:
- Spry version (spry --version)
- Deno version (deno --version)
- Operating system
- Minimal reproduction steps
- Error messages and logs

How is this guide?

Troubleshooting

On this page