Troubleshooting - larralapid/personal-backstage GitHub Wiki

Troubleshooting

🐛 Known Issues

Native Dependencies

Some backend features require native compilation:

  • isolated-vm - Used for secure templating
  • better-sqlite3 - Database operations

Workaround: Use frontend-only mode for full functionality without these dependencies.

Current Limitations

  • Scaffolder plugin unavailable (requires native deps)
  • In-memory database only (production needs external DB)
  • No authentication configured (suitable for personal use)

🔧 Common Solutions

Frontend-Only Mode

If you encounter native dependency issues, run the frontend only:

yarn workspace app start

Test Failures

If tests fail, check:

  1. Node.js version (requires 18+)
  2. Yarn version (requires 4.4.1+)
  3. Configuration files are valid YAML

Configuration Issues

Validate your configuration:

node test-config.js

📞 Getting Help

For additional support: