Deploy ForgeDeployForge
Deploy ForgeDeployForge
Back to Home

Troubleshooting

This guide covers common issues and their solutions. If you don't find your answer here, check the deployment logs for specific error messages.

Deployment Issues

Deployment fails immediately

Symptoms: Deployment status shows "Failed" right after starting.

Solutions:

  1. Check GitHub connection

    • Go to Deploy Forge → Settings
    • Verify connection shows "Connected"
    • If not, click "Connect to GitHub" to re-authorize

  2. Verify repository access

    • The GitHub App must have access to your repository
    • Go to GitHub → Settings → Applications → Deploy Forge → Configure
    • Ensure your repository is selected

  3. Check workflow file (GitHub Actions method)

    • Verify workflow file exists in .github/workflows/
    • Ensure workflow has workflow_dispatch trigger
    • See Workflows for requirements

Build succeeds but deployment fails

Symptoms: GitHub Actions shows success, but Deploy Forge shows failed.

Solutions:

  1. Check artifact upload

    • Your workflow must upload an artifact
    • Verify actions/upload-artifact step exists and succeeds
    • Check artifact is a ZIP file, not a directory

  2. Check file permissions

    • WordPress must have write access to wp-content/themes/
    • Verify directory permissions: 755 for folders, 644 for files

  3. Check disk space

    • Insufficient space prevents file extraction
    • Clear old backups or increase disk allocation

"No artifacts found" error

Symptoms: Logs show "No artifacts found" after build completes.

Solutions:

  1. Your workflow didn't upload an artifact
  2. The artifact name doesn't match what Deploy Forge expects
  3. The artifact expired (GitHub retains artifacts for 90 days by default)

Fix by adding to your workflow:

- uses: actions/upload-artifact@v4
  with:
    name: theme-build
    path: your-build-output.zip

Deployment stuck in "Building" state

Symptoms: Status shows "Building" for longer than expected.

Solutions:

  1. Check GitHub Actions

    • Go to your repository → Actions tab
    • Find the workflow run and check its status
    • If queued, GitHub may be experiencing delays

  2. Cancel and retry

    • Click "Cancel" on the stuck deployment
    • Trigger a new deployment manually

  3. Check WP-Cron

    • Deploy Forge uses WP-Cron to poll for completion
    • If your site has low traffic, cron may not run frequently
    • Consider setting up a system cron instead

Automatic Deployment Issues

Push not triggering deployment

Symptoms: You push code but no deployment starts.

Solutions:

  1. Verify branch matches

    • Deployments only trigger for your configured branch
    • Pushing to develop won't trigger if branch is set to main
    • Check your branch setting in the Deploy Forge dashboard

  2. Check site connection

    • Go to Deploy Forge in WordPress admin
    • Verify your site shows as Connected
    • If not connected, click Connect to re-establish (you'll be redirected to the Deploy Forge app to complete setup)

  3. Check deployment history

    • Go to Deploy Forge → History
    • A deployment may have been created but failed for another reason

"Invalid signature" error

Symptoms: Deployment logs show signature validation failed.

Solution: Your site's connection may have become corrupted or out of sync.

  1. In WordPress admin, go to Deploy Forge
  2. Click Disconnect
  3. Click Connect to re-establish the connection (you'll be redirected to the Deploy Forge app to complete setup)
  4. Try pushing again

Connection Issues

"Failed to connect to GitHub"

Symptoms: Connection test fails or GitHub operations error.

Solutions:

  1. Re-authorize

    • In WordPress admin, go to Deploy Forge
    • Click Disconnect then Connect
    • Complete the setup in the Deploy Forge app

  2. Check GitHub status

  3. Check firewall/hosting

    • Your server must allow outbound HTTPS to api.github.com
    • Some hosting providers block external API calls

"Rate limit exceeded"

Symptoms: GitHub API errors mentioning rate limits.

Solutions:

  1. Wait for reset

    • GitHub rate limits reset hourly
    • Check the X-RateLimit-Reset header for exact time

  2. Reduce deployment frequency

    • Batch commits instead of pushing frequently
    • Use manual deployments during heavy development

WordPress Issues

Theme not appearing after deployment

Symptoms: Deployment succeeds but theme unchanged.

Solutions:

  1. Clear cache

    • Clear your caching plugin (WP Super Cache, W3 Total Cache, etc.)
    • Clear server-level cache if applicable
    • Clear CDN cache (Cloudflare, etc.)

  2. Verify target directory

    • Check Deploy Forge → Settings for target theme directory
    • Ensure it matches your active theme's folder name

  3. Check file extraction

    • The ZIP structure must match WordPress theme structure
    • Theme files should be at root of ZIP, not nested in extra folders

Permission denied errors

Symptoms: Logs show "Permission denied" or "Unable to write".

Solutions:

  1. Fix directory permissions

    chmod 755 wp-content/themes/
chmod 755 wp-content/themes/your-theme/

  2. Fix file ownership

    chown -R www-data:www-data wp-content/themes/your-theme/

    (Replace www-data with your web server's user)

  3. Contact hosting support

    • Some managed hosts restrict file operations
    • Ask them to grant write access to themes directory

Getting More Help

Enable Debug Logging

  1. Go to Deploy Forge → Settings
  2. Enable Debug Logging
  3. Trigger a deployment
  4. Check Deploy Forge → Logs for detailed output

Check WordPress Debug Log

Add to wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Check wp-content/debug.log for errors.

Collect Information for Support

When contacting support, include:

  • WordPress version
  • PHP version
  • Deploy Forge version
  • Deployment method (GitHub Actions or Direct Clone)
  • Error messages from logs