Troubleshooting

Solutions to common issues when using gitlab-summary.

Authentication Issues

“Unable to authenticate with GitLab”

Symptoms:

All commands fail immediately
Error mentions authentication or 401

Causes:

Token not stored
Token expired
Token lacks required scope
Wrong GitLab URL

Solutions:

Check if token is stored:

  gitlab-summary token show

Verify URL:

  gitlab-summary url show

Reset token:

  gitlab-summary token clear
gitlab-summary token set --url https://gitlab.example.com

Test token manually:

  curl -H "PRIVATE-TOKEN: your-token" \
  https://gitlab.example.com/api/v4/user

Check token scope:

Log into GitLab
User Settings → Access Tokens
Verify read_api is checked

“Token not found”

Symptom: Error says no token configured

Solution:

  gitlab-summary token set --url https://gitlab.example.com

Token Works in Browser but Not CLI

Causes:

Different GitLab URL configured
Token not stored via CLI command

Solutions:

  # Verify URL matches browser
gitlab-summary url show

# Set correct URL
gitlab-summary url set --url https://your-gitlab-url.com

# Store token
gitlab-summary token set --url https://your-gitlab-url.com

Connection Issues

“Connection refused”

Causes:

Wrong URL
GitLab instance down
Firewall/network blocking

Solutions:

Test connectivity:

  # Test basic connectivity
ping gitlab.example.com

# Test HTTP(S)
curl https://gitlab.example.com

# Test API specifically
curl https://gitlab.example.com/api/v4/version

Verify URL:

  gitlab-summary url show

# Fix if wrong
gitlab-summary url set --url https://correct-url.com

Check firewall:

Corporate firewall may block API access
VPN may be required
Proxy configuration needed

SSL Certificate Errors

Symptom: SSL/TLS verification failed

Causes:

Self-signed certificate
Expired certificate
Certificate name mismatch

Solutions:

For development (HTTP if available):

  gitlab-summary url set --url http://gitlab.local

For production:

Install proper SSL certificate on GitLab
Install CA certificate on client machine
Use organization’s trusted certificates

Dashboard Issues

Dashboard Won’t Load

Symptom: Browser shows connection error

Causes:

Server not running
Port in use
Browser cache

Solutions:

Check if server is running:

  ps aux | grep gitlab-summary

Start server if not running:

  gitlab-summary serve --group my-org --open

Try different port:

  gitlab-summary serve --group my-org --port 8080

Clear browser cache:

Chrome/Edge: Ctrl+Shift+Delete (Windows) or Cmd+Shift+Delete (Mac)
Firefox: Ctrl+Shift+Delete
Safari: Cmd+Option+E

SSE Connection Drops

Symptom: Dashboard stops updating, shows “disconnected”

Causes:

Network instability
Proxy timeout
Server restart

Solutions:

Refresh browser:

  # Hard refresh
Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

Check network:

  # Test connection
curl http://localhost:5100/api/health

Restart server:

  # Stop
Ctrl+C

# Start
gitlab-summary serve --group my-org --open

Dashboard Shows Old Data

Causes:

Browser cache
Old session
Time range too large

Solutions:

Hard refresh:

  Ctrl+Shift+R (Windows/Linux)
Cmd+Shift+R (Mac)

Change time period:

Use dropdown to select shorter range
Reduces cached data

Clear localStorage:

  // In browser console (F12)
localStorage.clear();
location.reload();

AI Analysis Issues

“AI analysis failed”

Causes:

GitHub CLI not installed
Not authenticated with GitHub
No Copilot subscription
Network issues

Solutions:

Install GitHub CLI:

  # macOS
brew install gh

# Windows
winget install --id GitHub.cli

# Linux (Debian/Ubuntu)
sudo apt install gh

Authenticate:

  gh auth login
# Follow prompts

Verify Copilot access:

  gh copilot --version

Test manually:

  gh copilot explain "npm install failed"

Empty AI Responses

Causes:

Insufficient log data
Generic error
Network timeout

Solutions:

Check full logs in GitLab:

May have more context
Some logs truncated in API response

Ask more specific follow-up:

  Initial: "Build failed"
Follow-up: "What specific line in the log shows the root cause?"

Customize system prompt:

Settings → System Prompt
Add: “Provide detailed analysis with line numbers”

AI Analysis Not Caching

Causes:

Permission issues
Disk space
File corruption

Solutions:

Check permissions:

  # macOS/Linux
ls -la ~/.gitlab-summary/
chmod 644 ~/.gitlab-summary/ai-analysis-cache.json

Check disk space:

  df -h ~

Reset cache:

  # Backup first
cp ~/.gitlab-summary/ai-analysis-cache.json ~/ai-cache-backup.json

# Remove corrupted file
rm ~/.gitlab-summary/ai-analysis-cache.json

# Restart dashboard

Performance Issues

Slow Pipeline Queries

Symptoms:

Commands take minutes to complete
Dashboard loading slow
Timeouts

Causes:

Large time range
Many projects
GitLab API rate limiting
Network latency

Solutions:

Reduce time range:

  # Instead of 30 days
gitlab-summary pipelines --group my-org --since 30d

# Use 1 day
gitlab-summary pipelines --group my-org --since 1d

Filter by project:

  gitlab-summary pipelines --group my-org --project api-service

Use smaller group:

  # Instead of entire org
gitlab-summary pipelines --group company

# Use specific team
gitlab-summary pipelines --group company/engineering/backend

Increase update interval:

  # Dashboard updates less frequently
gitlab-summary serve --group my-org --interval 120

High Memory Usage

Causes:

Large datasets (1000+ pipelines)
Dashboard running for days
Memory leak (rare)

Solutions:

Restart dashboard:

  Ctrl+C
gitlab-summary serve --group my-org --open

Reduce data scope:

  gitlab-summary serve --group my-org --since 1d --interval 60

Close unused browser tabs:

Each dashboard tab uses memory

Installation Issues

“Command not found” After Global Tool Install

Cause: .NET tools directory not in PATH

Solutions:

macOS/Linux:

  # Add to PATH temporarily
export PATH="$PATH:$HOME/.dotnet/tools"

# Add permanently to ~/.bashrc or ~/.zshrc
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell:

  # Add temporarily
$env:PATH += ";$env:USERPROFILE\.dotnet\tools"

# Add permanently
[Environment]::SetEnvironmentVariable(
    "Path",
    $env:Path + ";$env:USERPROFILE\.dotnet\tools",
    "User"
)

“Permission denied” (macOS/Linux)

Cause: Executable not marked as executable

Solution:

  chmod +x gitlab-summary

macOS Security Warning

Symptom: “Cannot be opened because the developer cannot be verified”

Solutions:

Option 1: Remove quarantine:

  xattr -d com.apple.quarantine gitlab-summary

Option 2: System Preferences:

Try to run ./gitlab-summary
System Preferences → Security & Privacy
Click “Allow” for gitlab-summary

Data Issues

“Group not found”

Causes:

Invalid group ID/path
No access permission
Token lacks scope

Solutions:

Verify group exists:

Log into GitLab
Navigate to group
Note group ID from URL or settings

Check permissions:

Ensure you’re a member
Token must have read_api scope

Try group ID instead of path:

  # If path doesn't work
gitlab-summary pipelines --group my-org/team

# Try numeric ID
gitlab-summary pipelines --group 2217

“No pipelines found”

Causes:

Time range too narrow
No recent pipeline activity
Projects have no pipelines
Filter too restrictive

Solutions:

Expand time range:

  gitlab-summary pipelines --group my-org --since 7d

Remove project filter:

  # Shows all projects
gitlab-summary pipelines --group my-org

Check in GitLab UI:

Verify pipelines exist
Check time range matches

Logging & Debugging

Enable Verbose Logging

Currently, gitlab-summary doesn’t have verbose logging mode, but you can:

Check API responses:

  # Test GitLab API manually
curl -H "PRIVATE-TOKEN: your-token" \
  https://gitlab.example.com/api/v4/groups/my-org \
  | jq .

Browser DevTools (for dashboard):

  F12 → Console tab
Look for errors or warnings

Getting Help

Before Asking for Help

Collect this information:

  # Version
gitlab-summary --version

# Configuration
gitlab-summary url show
gitlab-summary token show

# Test connection
curl -H "PRIVATE-TOKEN: your-token" \
  https://your-gitlab-url.com/api/v4/user

Where to Get Help

GitHub Issues: Report bugs

GitHub Discussions: Ask questions

Include in Report:

gitlab-summary version
Operating system
Error message (full text)
Steps to reproduce
Configuration (mask tokens!)

Troubleshooting

Troubleshooting link

Authentication Issues link

“Unable to authenticate with GitLab” link

“Token not found” link

Token Works in Browser but Not CLI link

Connection Issues link

“Connection refused” link

SSL Certificate Errors link

Dashboard Issues link

Dashboard Won’t Load link

SSE Connection Drops link

Dashboard Shows Old Data link

AI Analysis Issues link

“AI analysis failed” link

Empty AI Responses link

AI Analysis Not Caching link

Performance Issues link

Slow Pipeline Queries link

High Memory Usage link

Installation Issues link

“Command not found” After Global Tool Install link

“Permission denied” (macOS/Linux) link

macOS Security Warning link

Data Issues link

“Group not found” link

“No pipelines found” link

Logging & Debugging link

Enable Verbose Logging link

Getting Help link

Before Asking for Help link

Where to Get Help link

See Also link

Troubleshooting

Authentication Issues

“Unable to authenticate with GitLab”

“Token not found”

Token Works in Browser but Not CLI

Connection Issues

“Connection refused”

SSL Certificate Errors

Dashboard Issues

Dashboard Won’t Load

SSE Connection Drops

Dashboard Shows Old Data

AI Analysis Issues

“AI analysis failed”

Empty AI Responses

AI Analysis Not Caching

Performance Issues

Slow Pipeline Queries

High Memory Usage

Installation Issues

“Command not found” After Global Tool Install

“Permission denied” (macOS/Linux)

macOS Security Warning

Data Issues

“Group not found”

“No pipelines found”

Logging & Debugging

Enable Verbose Logging

Getting Help

Before Asking for Help

Where to Get Help

See Also