Troubleshooting

This guide covers solutions to common problems you might encounter with Phaset. If you don’t find your issue here, reach out at [email protected] or join our Discord community.

Installation Issues

Command not found: phaset

Problem: After installing, running phaset gives “command not found”

Solution: Add ~/.local/bin to your PATH:

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

Make it permanent by adding this line to your shell profile:

# For Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# For Bash (Linux default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Then restart your terminal or run source ~/.zshrc (or ~/.bashrc).

Node.js version error

Problem: Node.js version 24 or later is required

Solution:

1. Check your current version:

   node --version

2. Install Node.js 24 or later from nodejs.org

3. Verify the installation:

   node --version

Note: If you have multiple Node versions installed (via nvm, Volta, etc.), ensure version 24+ is active.

Installation fails during download

Problem: Installation script fails to download Phaset

Solution:

1. Check your internet connection

2. Verify you can access https://releases.phaset.dev

3. Check if you have curl or wget installed:

   curl --version
   wget --version

4. Try the manual installation from releases.phaset.dev

Permission denied errors during installation

Problem: Permission denied when installing or running Phaset

Solution:

1. Ensure you have write permissions to ~/.local/bin and ~/.phaset:

   mkdir -p ~/.local/bin ~/.phaset
   chmod 755 ~/.local/bin ~/.phaset

2. Don’t use sudo with the installer—it should install to your user directory

3. If running Phaset, ensure write permissions in your working directory for database files

Configuration Issues

Configuration file not found

Problem: Indication that the configuration file is not being picked up, though it should have been.

Solution:

1. Run phaset init to create a template configuration file
2. Ensure you’re running phaset start from the directory containing your config file
3. Check the file name is exactly phaset.config.json (case-sensitive)

See also “CLI not picking up local configuration”.

Missing required configuration values

Problem: Phaset won’t start, showing errors like Missing email.host value

Solution: Ensure all required fields are configured. The minimum required configuration is:

{
  "email": {
    "host": "smtp.yourprovider.com",
    "user": "[email protected]",
    "password": "your-smtp-password"
  },
  "phaset": {
    "bootstrap": {
      "organizationName": "Your Organization",
      "adminEmail": "[email protected]"
    }
  }
}

See the Configuration Guide for complete details.

CLI not picking up local configuration

Problem: CLI seems to ignore your phaset.config.json file

Solution:

1. Verify you’re in the correct directory:

   pwd
   ls -la phaset.config.json

2. Check the JSON syntax is valid (common issues: trailing commas, missing quotes)

3. As a workaround, copy the configuration to Phaset’s installation directory:

   cp phaset.config.json ~/.phaset/

4. Or use environment variables instead (see Configuration Guide)

Invalid JSON syntax

Problem: Unexpected token or JSON parsing errors

Solution:

1. Validate your JSON using a tool like jsonlint.com
2. Common issues:
   • Trailing commas after the last item in an array or object
   • Missing quotes around keys or string values
   • Unescaped quotes inside strings
   • Comments (JSON doesn’t support comments)

Example of invalid JSON:

{
  "email": {
    "host": "smtp.example.com", // ❌ No comments allowed
    "port": 465,  // ❌ Trailing comma before closing brace
  }
}

Authentication & Email Issues

Not receiving sign-in emails

Problem: Magic link emails never arrive

Solution:

1. Check spam/junk folder - sign-in emails may be filtered

2. Verify email configuration:

   # Check your config has correct SMTP details
   cat phaset.config.json | grep -A 6 "email"

3. Test SMTP connectivity:

   • Verify firewall allows outbound connections to your SMTP port

   • Many cloud providers block port 25—use 465 (SSL) or 587 (TLS)

   • Try connecting manually:

     telnet smtp.yourprovider.com 465

4. Check SMTP credentials:

   • For Gmail, use an app password, not your regular password
   • Verify username is correct (often your full email address)
   • Check password has no typos

5. Verify admin email:

   • Ensure BOOTSTRAP_ADMIN_EMAIL matches the email you’re trying to sign in with
   • Check for typos or extra whitespace

6. Check Phaset logs for SMTP errors when you attempt sign-in

Authentication failure loop in web app

Problem: After clicking magic link, redirected back to sign-in page repeatedly

Solution:

1. Clear browser storage:
   • Open browser console (F12)
   • Run: localStorage.clear()
   • Refresh the page and try signing in again
2. Check API/web app configuration match:
   • Web app’s window.APP_CONFIG.apiBaseUrl must point to your API
   • API’s auth.appUrl must point to your web app’s /app/finishSignIn path
   • Both must use the same protocol (http/https) and domain
3. Verify CORS settings:
   • API’s server.allowedDomains must include your web app’s domain
   • Check browser console for CORS errors
4. Check magic link hasn’t expired:
   • Default expiry is 15 minutes
   • Request a new sign-in link

Magic link says “Invalid or expired token”

Problem: Clicking the magic link shows an error

Solution:

1. Request a new link - magic links expire after 15 minutes (default)
2. Check the URL is complete - email clients sometimes break long URLs across lines
3. Verify JWT secret hasn’t changed - if you changed auth.jwtSecret after sending the link, tokens become invalid
4. Check system time - ensure your server’s clock is accurate (JWT validation is time-sensitive)

Cannot access web app (CORS errors)

Problem: Browser console shows blocked by CORS policy errors

Solution:

1. Check allowed domains in your API configuration:

   "server": {
     "allowedDomains": [
       "https://your-frontend-domain.com",
       "http://localhost:5173"
     ]
   }

2. Match the exact domain:

   • Include protocol (http:// or https://)
   • Include port if non-standard (:5173, :3000, etc.)
   • No trailing slashes

3. Restart the API after changing CORS configuration

4. For development only, you can temporarily use ["*"] to allow all domains, but never in production

API & Connectivity Issues

API won’t start

Problem: phaset start fails or exits immediately

Solution:

1. Check for port conflicts:

   # See what's using port 3000
   lsof -i :3000

   Kill the conflicting process or use a different port:

   phaset start --port 8080

2. Check configuration is valid - see Configuration Issues

3. Check Node.js version - must be 24 or later

4. Check logs for error messages when starting

5. Verify required files exist:

   ls -la ~/.phaset/phaset_api.mjs

API connection refused or timeout

Problem: Web app cannot connect to API

Solution:

1. Verify API is running:

   # Check if API is listening
   curl http://localhost:3000

2. Check firewall rules:

   • Allow inbound connections on API port (default 3000)
   • For cloud deployments, check security groups/firewall rules

3. Verify API URL in web app:

   • Open index.html
   • Check window.APP_CONFIG.apiBaseUrl matches your API endpoint
   • Include protocol and port: http://localhost:3000

4. Check network connectivity:

   • For remote API, ensure you can reach it: curl https://your-api.com
   • Check DNS resolution: nslookup your-api.com

5. For cloud deployments:

   • Verify the app deployed successfully
   • Check health check endpoint is passing
   • Review deployment logs for errors

Port already in use

Problem: Error: listen EADDRINUSE: address already in use :::3000

Solution:

1. Find what’s using the port:

   # On Linux/macOS
   lsof -i :3000
   
   # On Linux (alternative)
   netstat -tulpn | grep 3000

2. Kill the process:

   kill <PID>

3. Or use a different port:

   phaset start --port 8080

   Then update your web app’s apiBaseUrl accordingly.

Cannot connect to database

Problem: Database-related errors on startup

Solution:

1. Check write permissions in your working directory:

   ls -la
   # Verify you own the directory and files

2. Verify disk space:

   df -h .

3. Check database directory configuration:

   "storage": {
     "databaseDirectory": ""  // Empty = current directory
   }

4. For corrupted database, backup and delete database files to start fresh

Licensing Issues

License key is invalid or not activated

Problem: “License key is invalid or not activated” on startup

Solution:

1. Activate your license:

   phaset activate YOUR-LICENSE-KEY

2. Verify key format - should be PHASET-V1-XXXX-XXXX-XXXX

3. Check key matches major version:

   • A V1 key only works with Phaset 1.x
   • A V2 key only works with Phaset 2.x

4. Verify online connectivity - license validation requires internet access

5. Check license status:

   phaset license

License key is not eligible for this version

Problem: “License key is not eligible for this version of Phaset”

Solution:

Your license key’s major version doesn’t match the Phaset version you’re running.

• Phaset 1.x requires a PHASET-V1-... key
• Phaset 2.x requires a PHASET-V2-... key

Either:

• Downgrade to the correct major version
• Purchase a license for the current major version

License validation fails

Problem: Cannot validate license due to network errors

Solution:

1. Check internet connectivity:

   curl https://api.phaset.dev/prod/version/api

2. Check firewall allows outbound HTTPS to api.phaset.dev

3. Try manual validation:

   curl --request POST \
     --url 'https://api.phaset.dev/prod/licenses/validate?key=YOUR-KEY'

4. For airgapped environments, contact [email protected] for alternative licensing

Unable to invite more users or create more organizations

Problem: Error occurs when attempting to invite more users or create more organizations

Solution:

1. Free license limits:
   • 1 organization
   • 2 users (including admin)
2. Upgrade to a commercial license to remove these limits
3. Or remove unused users/organizations if you’re within limits but hitting the cap

Integration & Metrics Issues

Webhooks not triggering

Problem: Push/PR/deployment events not appearing in Phaset

Solution:

1. Verify webhook URL is correct:

   https://your-phaset-api.com/integration/event/{ORG_ID}/{RECORD_ID}/{TOKEN}

   Replace placeholders with your actual values

2. Check webhook is active in your VCS settings

3. Verify webhook events are selected - see Integration Guide for required events

4. Check webhook delivery logs in your VCS:

   • GitHub: Settings → Webhooks → Recent Deliveries
   • GitLab: Settings → Webhooks → Recent events
   • Look for failed deliveries and error messages

5. Verify network access - ensure your VCS can reach your API

6. Check Record ID matches - webhook URL must use correct Record ID

Metrics not appearing

Problem: DORA or engineering metrics show no data

Solution:

1. Verify webhook integration is working - see above

2. Check time range - default is last 30 days:

   • Ensure events occurred in this period
   • Try expanding the date range

3. Verify Record exists and matches webhook configuration

4. Check event types - some metrics require specific events:

   • Deployment Frequency: deployment events
   • Change Lead Time: commit + deployment events
   • Change Failure Rate: deployment + incident events

5. Allow time for processing - metrics may not show up until the day after (in order to get aggregation etc. correct)

Standards not updating

Problem: Standards checks show outdated or no results

Solution:

1. Standards only update via automation - cannot be updated in the UI
2. Verify CI integration is configured correctly:
   • See Integration Guide for setup
   • If GitHub: Verify you are using the provided GitHub Action
   • Else: Check your pipeline is running StandardLint manually
   • Verify API key and endpoint are correct
3. Check StandardLint output for errors:
   • Review CI logs for StandardLint execution
   • Verify standardlint.results.json file exists

Web App Issues

Web app shows blank page

Problem: Loading the web app shows nothing

Solution:

1. Check browser console (F12) for errors

2. Verify API endpoint is correct in index.html:

   <script>
     window.APP_CONFIG = { apiBaseUrl: 'http://localhost:3000' };
   </script>

3. Check API is running and accessible:

   curl http://localhost:3000

4. Clear browser cache and reload (Ctrl+Shift+R / Cmd+Shift+R)

5. Try a different browser to rule out browser-specific issues

6. Check static file server is running (if local), for example:

   python3 -m http.server 5173

Web app loads but shows errors

Problem: Web app displays error messages or broken features

Solution:

1. Check browser console for JavaScript errors

2. Verify API connectivity - most features require API access

3. Check authentication - try signing out and back in

4. Clear localStorage:

   localStorage.clear()

5. Verify web app version matches API version - major versions must align

Service Worker errors

Problem: Console shows service worker registration failures

Solution:

1. Service workers require HTTPS (except localhost)

   • For production, ensure you’re using HTTPS
   • For local dev, access via localhost not 127.0.0.1

2. Unregister old service workers:

   • Chrome: DevTools → Application → Service Workers → Unregister
   • Firefox: about:serviceworkers

3. Clear service worker cache and reload

Cloud Deployment Issues

DigitalOcean App Platform deployment fails

Problem: App fails to deploy or shows errors

Solution:

1. Check deployment logs in DigitalOcean dashboard

2. Verify container image settings:

   • Repository: phasetdev/phaset-api
   • Tag: latest
   • Registry: GitHub Container Registry

3. Check environment variables are set correctly - see Quickstart

4. Verify port configuration - HTTP port should be 3000

5. Check resource limits - ensure sufficient memory allocated

Netlify deployment issues

Problem: Web app deployment fails or shows errors

Solution:

1. Check build logs in Netlify dashboard

2. Verify _redirects file exists in root:

   /*   /index.html   200

3. Ensure all files uploaded - the entire web app folder should be deployed

4. Check for file size limits - free tier has limits on site size

5. Clear Netlify cache and redeploy

Data not persisting (DigitalOcean)

Problem: Data disappears after redeployment

Solution:

This is expected with the quickstart configuration. DigitalOcean App Platform uses ephemeral storage.

For persistent data:

1. Deploy to a VM or VPS with persistent storage
2. See Installation Deep Dive for production setup

Getting More Help

If you’ve tried the solutions above and still have issues:

Documentation

• Installation Deep Dive - Complete installation guide
• Configuration Guide - All configuration options
• Integration Guide - Setting up webhooks and automation

Community Support

• Discord Community - Chat with other users
• GitHub Discussions - Ask questions and share knowledge

Direct Support

• Email: [email protected]
• Commercial customers: Priority support included with license

When reporting issues, include:

• Phaset version (cat ~/.phaset/VERSION)
• Operating system and version
• Node.js version (node --version)
• Error messages (full text)
• Relevant configuration (sanitized of secrets)
• Steps to reproduce the issue