Troubleshooting

Common Issues

Projects Not Detected

Symptom: Project added but no commands appear.

Solution:

  1. Right-click the project → Rescan
  2. Check that build file exists (pom.xml, package.json, etc.)
  3. Verify file is in project root (not in subdirectory)

Terminal Not Starting

Symptom: Ctrl+T does nothing or shows error.

Solution:

  1. Check Java is installed: java -version
  2. Verify terminal font is set in Settings
  3. Try resetting layout: View → Reset Layout to Default

Commands Not Running

Symptom: Clicking a command does nothing.

Solution:

  1. Check command works in a regular terminal
  2. Verify working directory is correct
  3. Check for missing environment variables

Theme Not Changing

Symptom: Theme change doesn’t apply.

Solution:

  1. Restart Needlecast
  2. Check you’re not in portable mode with different config
  3. Verify theme file exists in settings directory

Log Viewer Not Working

Symptom: Log viewer stays empty or shows errors.

Solution:

  1. Verify .log files exist in project
  2. Check file permissions
  3. Try a different log file

Auto-Update Not Working

Symptom: No update notifications.

Solution:

  1. Check internet connection
  2. Verify Sparkle4j is configured
  3. Try manual update check: Help → Check for Updates

Getting Help

If you encounter an issue not covered here:

  1. Check the GitHub Issues
  2. Search existing discussions
  3. Create a new issue with:
    • Needlecast version
    • Operating system
    • Steps to reproduce
    • Expected vs actual behavior

Logs

Needlecast logs to ~/.needlecast/needlecast.log. This file contains:

  • Startup messages
  • Error traces
  • Command execution logs

Next Steps