Troubleshooting

This guide provides solutions for common issues you may encounter when using Legend. If you don’t find a solution here, check the container logs for detailed error messages and contact support if needed.

Check Container Logs

Most issues generate detailed error messages in the container logs. Use docker compose logs legend or docker logs legend to view recent log entries. Look for error messages, warnings, or stack traces that can help identify the root cause.

Installation Issues

Docker Not Running

Symptom: Legend container fails to start with errors about Docker daemon or socket connection.

Cause: Docker is not running or not properly installed.

Solution:

1. Verify Docker is installed: docker --version
2. Check Docker service status: systemctl status docker (Linux) or check Docker Desktop (macOS/Windows)
3. Start Docker if needed: systemctl start docker (Linux) or launch Docker Desktop
4. Verify Docker is running: docker ps
5. Try starting Legend again: docker compose up -d

Port Conflicts

Symptom: Legend container fails to start with “port already in use” error.

Cause: Another service is using port 3000 (or your configured port).

Solution:

1. Identify what’s using the port: sudo lsof -i :3000 (Linux/macOS) or netstat -ano | findstr :3000 (Windows)
2. Stop the conflicting service, or
3. Change Legend’s port in docker-compose.yml:

   ports:
     - "3001:3000"  # Change 3001 to an available port

4. Restart Legend: docker compose up -d
5. Access Legend at the new port: http://localhost:3001

Permission Errors

Symptom: Legend container fails to start with “permission denied” errors when accessing the data directory.

Cause: The container doesn’t have write permissions to the mounted data directory.

Solution:

1. Check directory permissions: ls -la ./data
2. Set correct ownership: sudo chown -R $USER:$USER ./data
3. Set correct permissions: chmod -R 755 ./data
4. Verify the container user can write: docker compose exec legend touch /app/data/test && docker compose exec legend rm /app/data/test
5. Restart Legend: docker compose up -d

Container Exits Immediately

Symptom: Legend container starts and immediately exits with code 1.

Cause: Configuration error, missing required environment variable, or database corruption.

Solution:

1. Check container logs: docker compose logs legend
2. Look for error messages about missing environment variables
3. Verify LEGEND_SESSION_SECRET is set and is exactly 64 hexadecimal characters
4. Check that the data directory exists and is writable
5. If database corruption is suspected, restore from a recent backup

Login Issues

Account Locked

Symptom: Unable to log in with message “Account locked” or “Too many failed attempts.”

Cause: Multiple failed login attempts triggered account lockout for security.

Solution:

1. Wait 15 minutes for automatic unlock
2. Or contact an administrator to manually unlock the account:
   • Navigate to Admin Panel > Users
   • Find the locked account
   • Click “Unlock Account”
3. Verify you’re using the correct email address and password
4. If you’ve forgotten your password, use the “Forgot password” link on the login page

Forgot Password

Symptom: Cannot remember password and unable to log in.

Cause: Forgotten or lost password.

Solution:

1. Click “Forgot password” on the login page
2. Enter your email address
3. Check your email for a password reset link (check spam folder too)
4. Click the link and set a new password
5. Log in with your new password

If you don’t receive the email:

• Verify email notifications are configured in Legend
• Check that your email address is correct in the system
• Contact an administrator to manually reset your password

OIDC Not Working

Symptom: “Sign in with OIDC” button doesn’t work or shows an error.

Cause: OIDC configuration is incorrect or the identity provider is unreachable.

Solution:

1. Verify OIDC is enabled in Admin Panel > Single Sign-On (OIDC)
2. Check that the issuer URL, client ID, and client secret are correct
3. Verify the redirect URI in your identity provider matches Legend’s callback URL
4. Test the connection using the “Test Connection” button
5. Check container logs for OIDC-related errors: docker compose logs legend | grep -i oidc
6. Ensure your identity provider is accessible from the Legend container
7. Verify the user is a member of an allowed group (if group restrictions are configured)

Session Expired

Symptom: Logged out unexpectedly or “Session expired” message appears.

Cause: Session timeout, browser cookies disabled, or session secret changed.

Solution:

1. Log in again
2. Ensure browser cookies are enabled for the Legend domain
3. Check that you’re accessing Legend via the correct URL (matching LEGEND_PUBLIC_APP_URL)
4. If sessions expire too quickly, this may indicate the session secret was changed (which invalidates all existing sessions)
5. For persistent issues, check container logs for session-related errors

Entity Issues

Tier Limit Reached

Symptom: Cannot create new entities, categories, tags, or groups. Error message about tier limits.

Cause: You’ve reached the maximum number of items allowed for your license tier.

Solution:

1. Review current usage in Admin Panel > License
2. Delete unused entities, categories, tags, or groups to free up space
3. Upgrade your license tier for higher limits:
   • Community: 5 landmarks, 5 people, 2 teams, no custom groups
   • Starter: 50 landmarks, 50 people, 20 teams, 5 custom groups
   • Professional: 200 landmarks, 200 people, 50 teams, 15 custom groups
   • Business: Unlimited landmarks, people, teams, and groups
4. Contact sales for upgrade options: [email protected]

Entity Not Showing

Symptom: Created entity doesn’t appear on the dashboard or in search results.

Cause: Access control restrictions, inactive status, or data synchronization delay.

Solution:

1. Verify the entity is active (not deactivated)
2. Check access control settings:
   • Navigate to the entity’s detail view
   • Review “Access Groups” and “Edit Groups”
   • Ensure your user account is in at least one of these groups (or the groups are empty for public access)
3. Clear browser cache and refresh the page
4. Check container logs for entity creation errors
5. Verify the entity was saved successfully by checking the data directory

Relationship Errors

Symptom: Cannot create relationships or relationships don’t appear correctly.

Cause: Circular dependencies, invalid entity references, or permission issues.

Solution:

1. Verify both entities exist and are active
2. Check that you have edit permissions for both entities
3. Avoid circular dependencies (A depends on B, B depends on A)
4. For ownership relationships, ensure the owner entity exists
5. Check container logs for relationship-related errors
6. Try deleting and recreating the relationship

Documentation Not Saving

Symptom: Documentation changes don’t persist or show an error when saving.

Cause: File system permissions, disk space, or invalid markdown syntax.

Solution:

1. Check that the data directory has write permissions
2. Verify sufficient disk space is available: df -h ./data
3. Check container logs for file system errors
4. Ensure the documentation content is valid markdown
5. Try saving a smaller document to isolate the issue
6. Verify the documentation file path is correct in the entity YAML

Performance Issues

Slow Search

Symptom: Search queries take a long time to return results.

Cause: Large catalog size, insufficient resources, or unoptimized search index.

Solution:

1. Check container resource usage: docker stats legend
2. Increase container memory limit if needed:

   services:
     legend:
       deploy:
         resources:
           limits:
             memory: 2G

3. Restart the container to rebuild the search index: docker compose restart legend
4. For very large catalogs (1000+ entities), consider upgrading server resources
5. Check container logs for search-related errors or warnings

Large Catalog

Symptom: Dashboard loads slowly, entity operations are sluggish.

Cause: Catalog has grown very large (1000+ entities).

Solution:

1. Increase container resources (CPU and memory)
2. Use filters to reduce the number of entities displayed
3. Consider archiving or deleting inactive entities
4. Split large catalogs into multiple Legend instances if needed
5. Ensure the database is on fast storage (SSD recommended)
6. Check container logs for performance warnings

High Memory Usage

Symptom: Container uses excessive memory or crashes with out-of-memory errors.

Cause: Large catalog, memory leak, or insufficient container memory limit.

Solution:

1. Check current memory usage: docker stats legend
2. Increase the memory limit in docker-compose.yml:

   services:
     legend:
       deploy:
         resources:
           limits:
             memory: 2G

3. Restart the container to clear memory: docker compose restart legend
4. Check container logs for memory-related errors
5. If the issue persists, contact support with logs and resource usage details

Slow Link Health Scans

Symptom: Link health scans take a long time or timeout.

Cause: Many links to check, slow network, or unreachable external services.

Solution:

1. Reduce the rate limit in Admin Panel > Link Health > Settings
2. Increase the timeout setting for slow links
3. Check network connectivity from the container: docker compose exec legend ping google.com
4. Exclude internal or slow links from health checks
5. Schedule scans during off-peak hours
6. Check container logs for link health scan errors

Licensing Issues

Expired License

Symptom: Warning banner about expired license, features disabled, or cannot access admin panel.

Cause: License has expired and grace period has ended.

Solution:

1. Navigate to Admin Panel > License
2. Check the expiration date and grace period status
3. Renew your license by entering a new license key
4. If you don’t have a new key, contact sales: [email protected]
5. Features will be restored immediately after applying a valid license

License Validation Errors

Symptom: Warning about license validation errors or features unexpectedly disabled.

Cause: Cannot reach the license server due to network issues or firewall restrictions.

Solution:

1. Verify outbound internet access: docker compose exec legend ping mylegend.io
2. Check firewall rules to ensure HTTPS (port 443) is allowed
3. If using a proxy, configure proxy settings in the container
4. Check container logs for license validation errors
5. Contact Legend support if you require an air-gapped deployment option

Invalid License Key

Symptom: Error message “Invalid license key” when applying a license.

Cause: License key is malformed, expired, or not valid for this instance.

Solution:

1. Verify the license key was copied correctly (no extra spaces or line breaks)
2. Check that the license key matches your Legend instance ID
3. Ensure the license key hasn’t expired
4. Contact support if you believe the key should be valid: [email protected]
5. For trial licenses, verify the trial period hasn’t ended

Features Not Unlocked

Symptom: Applied a license key but features are still restricted.

Cause: License key applied but container not restarted, or license doesn’t include the expected features.

Solution:

1. Restart the container to apply the new license: docker compose restart legend
2. Verify the license tier in Admin Panel > License
3. Check that the license key matches the tier you purchased
4. Clear browser cache and refresh the page
5. Check container logs for license-related messages
6. Contact support if features should be available but aren’t

Getting Help

If you can’t resolve an issue using this guide, you have several support options based on your license tier:

Community Tier Support

• Documentation: Comprehensive guides and troubleshooting (you’re reading it!)
• Community Forum: Ask questions and share solutions at https://community.mylegend.io
• GitHub Issues: Report bugs and request features at https://github.com/legendapp/legend/issues

Starter Tier Support

• All Community tier support, plus:
• Email Support: Priority email support at [email protected]
• Response Time: 48-hour response time during business days
• Bug Fixes: Priority bug fixes for critical issues

Professional Tier Support

• All Starter tier support, plus:
• Priority Support: Prioritized handling of support requests over email
• Faster Response Time: Expedited responses during business days

Business Tier Support

• All Starter tier support, plus:
• Priority Support: Dedicated support channel with 24-hour response time
• Phone Support: Phone support during business hours (by appointment)
• Dedicated Account Manager: Single point of contact for all support issues
• Custom Integrations: Assistance with custom integrations and deployments
• Onboarding Support: Help with initial setup and configuration

Providing Information for Support

When contacting support, include the following information to help resolve your issue quickly:

1. Legend Version: Check in Admin Panel > About or run docker compose exec legend legend --version
2. License Tier: Community, Starter, Professional, or Business
3. Error Messages: Exact error messages from the UI and container logs
4. Steps to Reproduce: Detailed steps to reproduce the issue
5. Environment Details:
   • Operating system and version
   • Docker version: docker --version
   • Docker Compose version: docker compose version
   • Server resources (CPU, memory, disk)
6. Container Logs: Recent logs from docker compose logs legend
7. Configuration: Relevant environment variables (excluding secrets)

Reporting Security Issues

If you discover a security vulnerability, please report it responsibly:

• Email: [email protected]
• Do not open public GitHub issues for security vulnerabilities
• Include detailed information about the vulnerability and steps to reproduce
• We will acknowledge receipt within 24 hours and provide a timeline for resolution

Common Log Messages

Here are some common log messages and what they mean:

INFO: Legend started successfully

• Normal startup message
• No action needed

WARN: Session secret is using default value

• You’re using the default session secret, which is a security risk
• Generate a new secret and update your configuration

ERROR: Failed to connect to database

• Database file is missing or corrupted
• Check that the data directory is mounted correctly
• Restore from backup if needed

ERROR: License validation failed

• License key is invalid, expired, or cannot be validated
• Check your license key and network connectivity
• Contact support if the issue persists

WARN: Rate limit exceeded for IP [address]

• Too many requests from a single IP address
• This is normal for automated tools or heavy usage
• Adjust rate limit settings if needed

Next Steps

If you’ve resolved your issue, return to the Admin Guide Overview to explore other administrative features. If you need further assistance, use the support options listed above.