Troubleshooting

This page covers common issues you might encounter when using the Bluebag CLI and how to resolve them.

Authentication Issues

Authentication Failed

Symptoms: "Authentication failed" or "Token expired" error

Solutions:

1. Clear stored credentials:

bluebag logout

2. Re-authenticate:

bluebag auth

3. Ensure you have access to the organization and project

Browser Doesn't Open

Symptoms: The authentication browser window doesn't open automatically

Solutions:

1. Copy the URL from the terminal manually
2. Paste it into your browser
3. Or disable auto-open and use the URL directly:

export BLUEBAG_OPEN_BROWSER=0
bluebag auth

Permission Denied

Symptoms: "Permission denied" errors when pushing or pulling

Solutions:

• Verify you're a member of the organization
• Check that you have write access to the project
• Contact your organization admin to grant access

No Organizations Found

Symptoms: "No organizations found" during authentication

Solutions:

1. Visit the Bluebag web app
2. Create a new organization or join an existing one
3. Run bluebag auth again

Push Issues

Skill Validation Errors

Symptoms: Push fails with validation errors

Solutions:

• Check the error message for specific issues
• Verify your SKILL.md has valid YAML frontmatter
• Ensure file types are allowed
• Check file sizes don't exceed limits

Upload Verification Timeout

Symptoms: "Verification timeout" or upload seems stuck

Solutions:

• Wait a bit longer—large Skills take time to verify
• Check your internet connection
• Try pushing again if it times out
• Push fewer Skills at once

Conflict Detected

Symptoms: Push blocked due to conflict with remote changes

Solutions:

• Pull first to get remote changes: bluebag pull
• Or force push to overwrite: bluebag push --force
• See Conflict Resolution for details

Pull Issues

Skill Not Found

Symptoms: "Skill not found" when pulling a specific Skill

Solutions:

• Verify the Skill name is correct
• Check if the Skill exists in your project (via dashboard)
• Ensure you're authenticated to the correct project

Download Failed

Symptoms: Files fail to download

Solutions:

• Check your internet connection
• Try pulling again
• Pull one Skill at a time to isolate the issue

Conflicts After Pull

Symptoms: You accidentally pulled and overwrote local changes

Solutions:

• Check if you have the changes in version control (git)
• Restore from git: git checkout -- skills/my-skill/
• If not using git, use bluebag push --force to restore from local if you have a backup
• Always commit important changes before pulling

Configuration Issues

No Configuration Found

Symptoms: "No .bluebagrc found" or similar

Solutions:

1. Run authentication in your project directory:

cd your-project
bluebag auth

2. Or manually create .bluebagrc:

{
  "organizationId": "your-org-id",
  "projectId": "your-project-id",
  "skillsDir": "skills"
}

Wrong Project

Symptoms: Skills sync with the wrong project

Solutions:

1. Check your .bluebagrc configuration
2. Re-authenticate to select the correct project:

bluebag auth

Skills Directory Not Found

Symptoms: "Skills directory not found" error

Solutions:

1. Create the skills directory:

mkdir skills

2. Or update skillsDir in .bluebagrc to point to your Skills location

Network Issues

Connection Timeout

Symptoms: Operations timeout or hang

Solutions:

• Check your internet connection
• Try again in a few minutes
• Check if Bluebag services are available

SSL/TLS Errors

Symptoms: Certificate or SSL errors

Solutions:

• Ensure your system time is correct
• Update your Node.js version
• Check if you're behind a corporate proxy

File Issues

Binary File Rejected

Symptoms: "File appears to be binary" error

Solutions:

• Remove binary files not in the whitelist
• Use allowed binary formats: .ttf, .pdf, .gz
• Convert files to text formats where possible

File Too Large

Symptoms: "File exceeds size limit" error

Solutions:

• Reduce file size (compress, trim content)
• Split into smaller files
• Host large assets externally

Unsupported Extension

Symptoms: "Unsupported file extension" error

Solutions:

• Remove or rename the file
• Use a supported extension
• See Validation for allowed types

Getting Help

If you're still having issues:

1. Check the error message carefully for specific guidance
2. Review the relevant documentation section
3. Ask on Discord for community support
4. Contact support with details about the issue

When reporting issues, include:

• The command you ran
• The complete error message
• Your Node.js version (node --version)
• Your CLI version (bluebag --version)