Frequently Asked Questions

Find answers to common questions about BugPin, the self-hosted visual bug reporting tool. Topics cover Docker installation errors, widget configuration, CORS troubleshooting, GitHub integration, authentication, and database management.

Installation

How do I check if BugPin is running?

Run one of the following commands depending on your installation method:

# Docker
docker ps | grep bugpin

# Bun
curl http://localhost:7300/health

If the Docker container shows Up ... (healthy) or the health endpoint returns a response, BugPin is running. See Health Checks for more details.

Why can't I access the Admin Console?

There are several things to check:

1. Server is running — Verify BugPin is running using the health check above
2. Port is accessible — Make sure nothing else is using port 7300 and check your firewall settings
3. Check logs — Run docker logs bugpin (Docker) or check console output (Bun) for errors. See Logging for detailed debugging

Why is my Docker container stuck in a restart loop?

This usually means the application is crashing on startup due to a permission error. Check the logs:

docker logs bugpin

If you see EACCES: permission denied, open '/data/.secret', the container runs as user bun (UID 1000) but the host ./data directory is owned by root.

Fix it by setting the correct ownership:

sudo chown -R 1000:1000 ./data
docker compose up -d

tip

To avoid this on fresh installs, always set permissions before starting the container:

mkdir -p data
sudo chown -R 1000:1000 data
docker compose up -d

Alternatively, use a named volume instead of a bind mount — Docker manages permissions automatically. See Docker Installation.

How do I fix "Permission denied" or "Unable to write to database" errors?

Check and fix volume permissions:

docker exec bugpin ls -la /data
# Should show bugpin.db with write permissions

# If not, fix permissions:
sudo chown -R 1000:1000 ./data

See File Permissions for more details.

What do I do when port 7300 is already in use?

Find what's using the port and either stop that process or change BugPin's port:

# Find what's using port 7300
sudo lsof -i :7300

# Or change BugPin's port in docker-compose.yml:
ports:
  - "8080:7300"  # Use port 8080 instead

See Custom Port for Docker configuration details.

Widget

Why is the BugPin widget not appearing on my website?

Check these in order:

1. Script is loaded — Open browser DevTools → Network tab and look for the widget.js request (should return status 200)
2. Browser console — Open DevTools → Console and look for BugPin-related errors (CORS errors, invalid API key, script loading errors)
3. API key is correct — Ensure the data-api-key attribute matches your project's API key exactly, with no typos or extra spaces
4. Script URL is correct — Ensure the src attribute points to your BugPin server (e.g., https://bugpin.example.com/widget.js)

See the Widget Installation Guide for setup instructions.

Why am I getting an "Invalid API Key" error?

The API key doesn't match any active project. To fix this:

1. Go to Projects in the Admin Console
2. Verify the project is active (not paused)
3. Copy the API key again
4. Update your widget configuration
5. Clear browser cache and reload the page

Why is the widget not sending reports?

Check the following:

1. Network connectivity — Open DevTools → Network tab, click the widget submit button, and look for the POST request to /api/widget/submit
2. CORS configuration — If you see CORS errors, go to Settings → Security → Domain Whitelist and add your website domain. See Domain Whitelisting
3. Browser console errors — Look for JavaScript errors or network failures
4. Rate limiting — If you see 429 (Too Many Requests) errors, check Settings → Security → Rate Limiting to adjust the limits (default: 10 requests per minute per API key). See Rate Limiting

What does "Project Paused" mean in the widget?

The project associated with your API key is inactive. Go to Projects in the Admin Console, find your project, and click "Resume" to reactivate it.

How do I customize the widget button and colors?

The widget supports extensive customization through data attributes or the Admin Console.

Using data attributes:

<script src="https://bugpin.example.com/widget.js"
  data-api-key="your-api-key"
  data-position="bottom-left"
  data-button-text="Send Feedback"
  data-theme="dark">
</script>

Available attributes include data-position (bottom-right, bottom-left, top-right, top-left), data-button-text, and data-theme (light, dark).

Using the Admin Console:

Go to Projects → Select project → Widget tab. You can configure button shape, icon, colors (light/dark mode), tooltip text, hover effects, and more.

See the Widget Configuration Reference for all available options including colors, button appearance, and feature toggles.

How do I open the widget programmatically?

Use the JavaScript API to control the widget from your own code:

// Open the bug report dialog
BugPin.open();

// Close the bug report dialog
BugPin.close();

You can also initialize the widget programmatically instead of using data attributes:

await BugPin.init({
  apiKey: 'your-api-key',
  serverUrl: 'https://bugpin.example.com',
  position: 'bottom-right',
  theme: 'dark'
});

This is useful for hiding the default launcher button and triggering the dialog from a custom button. See JavaScript API and Programmatic Initialization for details.

What file types and sizes are supported for attachments?

Users can attach images and videos to their bug reports:

Type	Accepted Formats	Max Size
Images	PNG, JPG/JPEG, GIF, WebP	10 MB per file
Videos	MP4, WebM, MOV, AVI	50 MB per file
Screenshots	Automatic capture	5 MB

Users can attach multiple files by dragging and dropping or using the file picker. Unsupported formats or oversized files are rejected with an error message. See Screenshot Settings for capture configuration.

What data is automatically captured in bug reports?

When a user submits a report, BugPin automatically captures the following metadata alongside the user's description and screenshots:

• Browser info — Name, version, and user agent
• Device info — Device type (desktop, tablet, mobile), OS, and OS version
• Page context — Current URL, page title, referrer, and page load time
• Viewport — Width, height, device pixel ratio, and screen orientation
• Console errors — JavaScript errors, warnings, and log messages with source and line number
• Network errors — Failed HTTP requests with URL, method, status code, and status text
• User activity trail — Recent interactions (clicks, input, navigation) with timestamps
• Storage keys — Names of cookies, localStorage, and sessionStorage keys (values are not captured)
• Environment — Timestamp and timezone

No sensitive data such as passwords, cookie values, or storage contents is captured — only key names for storage inspection.

Deployment

Why is the widget not loading on user websites (CORS error)?

This is typically caused by one of these issues:

Issue	Solution
Missing HTTPS	Enable HTTPS on both BugPin server and user website
Mixed content blocking	Ensure BugPin uses HTTPS, not HTTP
Reverse proxy stripping headers	Verify CORS headers pass through (Reverse Proxy Setup)
Firewall blocking	Ensure port 443 is accessible from user's network
Invalid SSL certificate	Use a valid SSL certificate (Let's Encrypt recommended)

Verify CORS headers are present:

curl -I https://bugpin.example.com/widget.js | grep -i "access-control"

Expected: access-control-allow-origin: *

Why are users getting 403 Forbidden when submitting reports?

The domain whitelist is blocking their website. Add the domain to project security settings:

1. Go to Projects → Select project
2. Navigate to Settings → Security
3. Add the domain to the whitelist (e.g., example.com)

Note: example.com automatically allows *.example.com subdomains. See Domain Whitelisting for more details.

How do I fix Content Security Policy (CSP) conflicts with the widget?

Users must add your BugPin server to their CSP configuration:

HTML meta tag:

<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://bugpin.example.com;
               connect-src 'self' https://bugpin.example.com;">

Nginx server configuration:

add_header Content-Security-Policy "script-src 'self' https://bugpin.example.com; connect-src 'self' https://bugpin.example.com;";

The required CSP directives are:

• script-src — Allow widget.js to load
• connect-src — Allow API requests to BugPin server

See the CSP Guide for framework-specific examples.

Reports

Why are reports not showing in the Admin Console?

Check the following:

1. Correct project selected — Verify you're viewing the correct project in the Reports filter dropdown
2. Database permissions — Run docker exec bugpin ls -la /data/bugpin.db and ensure it has write permissions
3. Server logs — Run docker logs bugpin --tail 100 and look for errors. See Logging for detailed debugging
4. Search filters — Clear all filters (status, priority, search) and try viewing "All Reports"

Why are screenshots not displaying?

This is caused by file storage issues, incorrect paths, or S3 misconfiguration.

For local storage:

# Verify uploads directory exists and is writable
docker exec bugpin ls -la /data/uploads/screenshots

For S3 storage:

• Verify S3 credentials in Settings → Storage
• Check bucket permissions
• Verify the bucket is in the correct region
• Test S3 connection with AWS CLI

Why can't I delete reports?

Only Admin users can delete reports. Editors and Viewers do not have delete permissions. Verify your user role in Settings → Users. See User Roles for a full permissions overview.

Authentication

What are the default login credentials for BugPin?

The default credentials are:

• Email: admin@example.com
• Password: changeme123

You should change these immediately after your first login. See the Quick Start Guide for initial setup.

How do I reset a forgotten password?

Run the password reset command:

# Docker
docker exec -it bugpin bun run reset-password admin@example.com

This will generate a new temporary password.

Why does my session keep expiring?

The session timeout may be too short. To increase it:

1. Go to Settings → Security
2. Increase "Session Max Age" (default is 7 days)

If you're getting "Unauthorized" errors, try logging out and back in, or clear your browser cookies. See Session Duration for configuration details.

How do I invite new users?

Admins can invite users through the Admin Console:

1. Go to Settings → Users
2. Click Invite User
3. Enter the user's email address and select a role (Admin, Editor, or Viewer)
4. The user receives an email with an invitation link

The invitation link expires after 7 days by default. You can adjust this (1–30 days) in Settings → Security. See Invitation Expiration for configuration details and User Roles for role descriptions.

How do I resend an expired invitation?

If an invitation has expired before the user accepted it:

1. Go to Settings → Users
2. Find the pending user in the list
3. Click the Resend button

This generates a new invitation link with a fresh expiration date and sends a new email to the user.

Integrations

Why is the GitHub integration not working?

Check the following:

1. Token permissions — Your GitHub Personal Access Token needs the repo scope (or read:org for organization repositories)
2. Test connection — Go to Settings → Integrations, edit the GitHub integration, and click "Test Connection"
3. Repository access — Ensure the repository exists, the token has access, and the repository is not archived
4. Logs — Run docker logs bugpin | grep -i github for GitHub-specific errors

See the GitHub Integration Guide for detailed setup instructions.

How do I choose between uploading files to GitHub or using links?

When configuring a GitHub integration, you can choose how screenshots and attachments are included in GitHub issues:

• Link mode (default) — Files are referenced as links back to your BugPin server. This is simpler and works without additional permissions.
• Upload mode — Files are uploaded directly to the GitHub repository. Files must be under 10 MB each; larger files are skipped.

To configure this:

1. Go to Settings → Integrations
2. Edit your GitHub integration
3. Toggle the Upload files to GitHub option

Upload mode requires the "Contents: Read and write" permission for fine-grained tokens, or the repo scope for classic tokens. See Required Permissions for token setup details.

Why are email notifications not sending?

Check these in order:

1. SMTP configuration — Go to Settings → Email and verify host, port (usually 587 for TLS, 465 for SSL), username, password, and encryption method
2. Test SMTP — Click "Test Email" in SMTP settings and check server logs for errors
3. Spam folder — Emails might be filtered as spam; add the BugPin sender address to your safe senders list
4. Email provider settings — Some providers (Gmail, Outlook) require app-specific passwords or have restrictions on third-party access

Reverse Proxy

How do I fix CORS errors when using a reverse proxy?

Don't strip or override CORS headers in your reverse proxy. BugPin handles CORS automatically.

Nginx — Don't add proxy_hide_header directives:

# DON'T do this:
# proxy_hide_header Access-Control-Allow-Origin;

# Headers should pass through:
proxy_pass http://localhost:7300;

Traefik — Don't add header modification middleware. BugPin handles CORS automatically.

Verify headers:

curl -I https://bugpin.example.com/widget.js | grep -i access-control

Expected: access-control-allow-origin: *

See the Reverse Proxy Setup Guide for full configuration examples for Nginx, Traefik, Caddy, and Apache.

How do I set up SSL certificates for BugPin?

Use Let's Encrypt with Certbot:

# Nginx
sudo certbot --nginx -d bugpin.example.com

# Apache
sudo certbot --apache -d bugpin.example.com

# Standalone
sudo certbot certonly --standalone -d bugpin.example.com

For Traefik, verify Let's Encrypt configuration in traefik.yml. See Reverse Proxy Setup for SSL configuration examples per proxy.

What causes a 502 Bad Gateway error?

BugPin is either not running or the reverse proxy can't connect to it. Check:

1. BugPin is running:

   docker ps | grep bugpin
   curl http://localhost:7300/health

2. Proxy configuration is correct — Nginx: check proxy_pass http://localhost:7300; Apache: check ProxyPass directive; Traefik: check service port in labels
3. Proxy logs:

   # Nginx
   sudo tail -f /var/log/nginx/error.log
   
   # Apache
   sudo tail -f /var/log/apache2/error.log
   
   # Traefik
   docker logs traefik

See Reverse Proxy Troubleshooting for more solutions.

Performance

Why is the dashboard loading slowly?

This can be caused by a large database, slow queries, or insufficient resources.

1. Check database size:

   docker exec bugpin du -sh /data/bugpin.db

2. Configure data retention — Go to Settings → System and reduce "Data Retention Days" (default: 90) to automatically clean up old reports
3. Check resource usage:

   docker stats bugpin

   Consider increasing Docker resource limits if needed.

See Performance Tuning for optimization tips.

Why are screenshot uploads slow?

Check the following:

1. Screenshot size limit — Configure in Settings → Widget (default: 5MB per screenshot); reduce if needed. See Screenshot Settings
2. Use S3 for storage — Configure S3 in Settings → Storage to offload storage to AWS S3, MinIO, or a compatible service for better performance
3. Network bandwidth — Check upload bandwidth between client and BugPin server

Database

What causes "Database is locked" or "SQLITE_BUSY" errors?

SQLite doesn't handle high concurrency well. These errors are usually transient.

Short term: Restart the BugPin server. The errors should resolve.

Long term: Reduce concurrent widget submissions if possible, or adjust rate limits.

How do I recover from database corruption?

If you see "Database disk image is malformed" errors:

Attempt repair:

# Backup first!
docker exec bugpin cp /data/bugpin.db /data/bugpin.db.backup

# Try to recover
docker exec bugpin sqlite3 /data/bugpin.db ".recover" | sqlite3 /data/bugpin_recovered.db

Restore from backup:

docker exec bugpin cp /data/backup/bugpin.db /data/bugpin.db
docker restart bugpin

How do I backup and restore my BugPin database?

All BugPin data is stored in the ./data/ directory, which contains:

• bugpin.db — The SQLite database
• uploads/ — Screenshots and file attachments

Backup:

# Stop BugPin for a consistent backup (recommended)
docker compose stop

# Copy the entire data directory
cp -r ./data ./data-backup-$(date +%Y%m%d)

# Restart BugPin
docker compose up -d

For a quick backup without downtime, you can use SQLite's built-in backup command:

docker exec bugpin sqlite3 /data/bugpin.db ".backup /data/bugpin-backup.db"
cp ./data/bugpin-backup.db /your/backup/location/

Restore:

docker compose stop
cp -r /your/backup/location/data ./data
sudo chown -R 1000:1000 ./data
docker compose up -d

tip

Set up a cron job or backup service to automate regular backups of the ./data/ directory. See Data Persistence and Backup for more details.

Getting Additional Help

If you can't find the answer to your question:

1. Check logs — View server logs to diagnose issues:

   # Docker
   docker logs bugpin --tail 100 --follow
   
   # Systemd
   sudo journalctl -u bugpin -n 100 -f

   See Logging for log analysis tips and common patterns.
2. Search documentation — Use the search bar to find relevant docs
3. GitHub Issues — Search existing issues or create a new one
4. When reporting issues, include:
   • BugPin version
   • Installation method (Docker, Bun)
   • Browser and version (for widget issues)
   • Relevant error messages from logs
   • Steps to reproduce

Related Documentation

• Quick Start Guide
• Docker Installation
• Bun Installation
• Server Configuration
• Widget Configuration
• Widget Installation
• User Roles
• GitHub Integration
• Security Settings
• Reverse Proxy Setup
• Monitoring & Logging
• API Reference