Skip to main content

Troubleshooting

Something not working? Start here. These are the issues people actually run into, in the order they usually run into them.

"First initialize this repository..."​

You ran a Protocol command but it can't find protocol.json in the current directory.

Fix: Make sure you're in your project's root directory, then run protocol init if you haven't already.

cd /path/to/your/project
protocol init

Protocol creates relative symlinks that point to ../project-config/. If Docker doesn't know about that directory, the symlinks point to nothing.

Fix: Mount the config directory as a volume in docker-compose.yml:

volumes:
  - '.:/var/www/html:rw'
  - '../myproject-config/:/var/www/myproject-config:rw'

The config directory needs to be a sibling to your project inside the container, matching the relative symlink paths.

Secrets Won't Decrypt​

"No key found" or decryption fails silently​

The encryption key isn't on this machine.

Fix: Get the key from wherever it lives (your dev machine, your password manager, a teammate) and install it:

protocol secrets:setup "your-64-character-hex-key"

Or if someone else has the key and can SCP it to you:

# On the machine that has the key:
protocol secrets:key --scp=you@this-machine

Wrong key​

If you have a key but decryption produces garbage, you have the wrong key. The key must match the one that was used to encrypt.

Fix: Get the correct key from whoever encrypted the secrets. There's no way to recover — AES-256-GCM doesn't guess.

Docker Issues​

Containers Don't Start​

Check Docker is running:

docker compose version

If that fails, Docker isn't installed or isn't running.

Check your docker-compose.yml:

docker compose config

If that shows errors, fix your compose file first.

"Container name not found" for exec/logs​

Protocol needs to know which container to target.

Fix: Add container_name to your protocol.json:

{
    "docker": {
        "container_name": "my-app-container"
    }
}

Containers Don't Survive Reboots​

Fix: Make sure Protocol is set to restart on reboot, and Docker starts on boot:

protocol cron:add
sudo systemctl enable docker

Watcher/Slave Mode Issues​

Changes Aren't Being Picked Up​

The watcher might have died quietly while its PID is still recorded.

Fix:

# See what's actually running
protocol status

# Restart everything
protocol stop
protocol start

"Slave mode is already running"​

A previous watcher is still alive, or the PID file is stale.

Fix:

# Try stopping gracefully
protocol git:slave:stop        # for branch mode
protocol deploy:slave:stop     # for release mode

# If that doesn't work, kill it manually
ps aux | grep -E "git-repo-watcher|release-watcher"
kill <pid>

# Clean up and restart
rm protocol.lock
protocol start

Slave Mode Stops After Local Changes​

By design. The watcher pauses when it detects uncommitted local changes to avoid overwriting your work. On a production node, there shouldn't be local changes.

Fix: Reset the local state and restart:

git checkout .
git clean -fd
protocol start

Git Issues​

"Not a git repository"​

You're not in a git repo. Protocol needs git to do almost everything.

Fix: Either cd into your git repo, or tell Protocol where it is:

protocol status --dir=/path/to/your/repo

Git Pull Fails or Hangs​

Usually an SSH key issue.

Fix:

# Test SSH access
ssh -T git@github.com

# If it fails, generate a deploy key
protocol key:generate
# Add the public key to GitHub as a deploy key

# Test again
git -C /path/to/repo fetch origin

"No GitHub CLI found"​

Release-based deployment needs the gh CLI for managing repository variables.

Fix:

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Then log in
gh auth login

Permission Issues​

"Permission denied" Running Protocol​

The binary isn't executable.

Fix:

chmod +x /path/to/protocol/protocol

Can't Write Config Files​

Protocol's own config file has restrictive permissions.

Fix:

chmod 755 /path/to/protocol/config/config.php

"Unable to create a git repo" During config:init​

You don't have write permissions in the parent directory.

Fix: Check permissions:

ls -la $(dirname $(pwd))

Protocol Commands Hang​

A lock file might be blocking. Protocol uses locks to prevent concurrent execution of certain commands.

Fix:

# Check for stale lock files
ls /tmp/sf.* 2>/dev/null

# Remove them (only if you're sure no other Protocol process is running)
rm /tmp/sf.*

Release Watcher Not Deploying​

Check the basics​

# Is the watcher running?
protocol status

# What does it think the active release is?
protocol deploy:status

# Any errors in the log?
protocol deploy:log

"Variable not found"​

The GitHub CLI can't access your repository variables.

Fix:

# Make sure gh is authenticated
gh auth status

# Make sure it can see your repo
gh repo view

Config File Errors on Startup​

Protocol's config/config.php might be empty or malformed.

Fix: Make sure it contains valid PHP:

<?php return array(
    'env' => 'your-environment-name',
);

Or just set your environment again:

protocol config:env your-environment

Still Stuck?​

# List all available commands
protocol list

# Get help on a specific command
protocol <command> --help

# Check everything
protocol status

# Turn on maximum verbosity for debugging
protocol <command> -vvv

For bug reports or feature requests, visit the GitHub repository.