Troubleshooting Guide

This guide helps you solve common issues you might encounter when using Flutter Bunny CLI.

Installation Issues

Command Not Found

Problem: After installation, flutter_bunny command is not found.

Solution:

Make sure the Dart pub cache bin directory is in your PATH:

Windows:
```
%APPDATA%\Pub\Cache\bin
```
macOS/Linux:
```
export PATH="$PATH":"$HOME/.pub-cache/bin"
```

Verify installation was successful:

dart pub global list | grep flutter_bunny

Try reinstalling:
```
dart pub global activate flutter_bunny
```

Permission Denied

Problem: Permission denied error when running Flutter Bunny CLI.

Solution:

macOS/Linux:

# Change permissions
chmod +x $HOME/.pub-cache/bin/flutter_bunny
 
# Or run with sudo (not recommended for regular use)
sudo flutter_bunny <command>

Windows: Run Command Prompt or PowerShell as Administrator.

Create Command Issues

Project Creation Fails

Problem: flutter_bunny create app fails with errors.

Solution:

Check if Flutter is properly installed:
```
flutter doctor
```
Try with verbose logging:
```
flutter_bunny create app --verbose
```
Make sure you have write permissions in the current directory.

Invalid Project Name

Problem: Error about invalid project name.

Solution: Use a name that follows Dart package naming conventions:

Lowercase letters
Underscores for spaces
No special characters

# Good
flutter_bunny create app --name my_app
 
# Bad (don't use these)
flutter_bunny create app --name MyApp
flutter_bunny create app --name "My App"
flutter_bunny create app --name my-app

Generate Command Issues

Generated Files in Wrong Location

Problem: Generated files are created in the wrong directory.

Solution:

Make sure you're running the command from the project root.
Check if your project follows the expected structure for the architecture you're using.

Configure custom output paths:

flutter_bunny config set generate.output_paths.screens "lib/ui/screens"
flutter_bunny config set generate.output_paths.widgets "lib/ui/widgets"
flutter_bunny config set generate.output_paths.models "lib/data/models"

Invalid Parameters Format

Problem: Error when using --params or --fields flags.

Solution: Make sure you're using the correct format:

Use quotes around the entire string
Use name:Type format
Separate multiple parameters with commas
No spaces around colons or commas

# Correct
flutter_bunny generate model --name User --fields "id:int,name:String,email:String"
 
# Incorrect
flutter_bunny generate model --name User --fields id:int, name:String, email:String

Build Command Issues

build_runner Not Found

Problem: Error that build_runner is not found.

Solution:

Make sure build_runner is in your pubspec.yaml:
```
dev_dependencies:
  build_runner: ^2.3.0
```
Run Flutter pub get:
```
flutter pub get
```

Conflicting Outputs

Problem: build_runner fails due to conflicting outputs.

Solution: Use the --delete-conflicting-outputs flag:

flutter_bunny build --delete-conflicting-outputs

Analyzer Errors Preventing Build

Problem: Analyzer errors prevent build_runner from completing.

Solution:

Fix the analyzer errors first:
```
flutter_bunny analyze --fix
```
Then run the build command again.

Analyze Command Issues

Too Many Errors

Problem: Analyzer shows too many errors, making it hard to focus.

Solution: Fix errors incrementally:

Start with fatal errors:

flutter_bunny analyze --no-fatal-warnings --no-fatal-infos

Then handle warnings:
```
flutter_bunny analyze --no-fatal-infos
```
Finally, handle info messages:
```
flutter_bunny analyze
```

Doctor Command Issues

False Positives

Problem: Doctor reports issues that are actually intentional or not relevant.

Solution:

Run with project-only flag to focus on your project issues:
```
flutter_bunny doctor --project-only
```

Create a custom configuration for doctor checks:

flutter_bunny config set doctor.checks.readme false

Config Command Issues

Config Not Persisting

Problem: Configuration changes don't seem to persist between runs.

Solution:

Check if you have write permissions to the config directory:

# macOS/Linux
ls -la ~/.flutter_bunny/
 
# Windows
dir %USERPROFILE%\.flutter_bunny

Try running with administrator privileges (Windows) or sudo (macOS/Linux).

Manually edit the config file (as a last resort):

# macOS/Linux
nano ~/.flutter_bunny/config.yaml
 
# Windows
notepad %USERPROFILE%\.flutter_bunny\config.yaml

Update Command Issues

Update Fails

Problem: flutter_bunny update command fails.

Solution:

Try with force flag:
```
flutter_bunny update --force
```

Uninstall and reinstall:

dart pub global deactivate flutter_bunny
dart pub global activate flutter_bunny

Template Issues

Custom Templates Not Working

Problem: Custom templates are not being used.

Solution:

Check your template directory structure:

# macOS/Linux
ls -la ~/.flutter_bunny/templates/
 
# Windows
dir %USERPROFILE%\.flutter_bunny\templates

Make sure template syntax is correct.

Make sure you're referencing the template correctly:

flutter_bunny create app --template my_custom_template

Dependency Issues

Version Conflicts

Problem: Dependency version conflicts.

Solution:

Check your Flutter version compatibility:
```
flutter --version
```
Try updating Flutter:
```
flutter upgrade
```
Run Flutter doctor to check for issues:
```
flutter doctor -v
```

Performance Issues

Commands Running Slowly

Problem: Flutter Bunny CLI commands are running slowly.

Solution:

Check your system resources (CPU, RAM, disk space).
Try clearing Flutter's cache:
```
flutter clean
```
Try clearing Dart's pub cache (use with caution):
```
dart pub cache clean
```

Debugging

Enable Verbose Logging

For detailed logs to help troubleshoot:

flutter_bunny --verbose <command>

Check Environment

To view your environment:

flutter_bunny doctor
flutter --version
dart --version

Check Logs

macOS/Linux:

cat ~/.flutter_bunny/logs/flutter_bunny.log

Windows:

type %USERPROFILE%\.flutter_bunny\logs\flutter_bunny.log

Getting Help

If you continue to experience issues:

Check the FAQ for common questions.
Search existing GitHub issues (opens in a new tab).
Open a new issue with:
- Command you're trying to run
- Error message
- Flutter and Dart versions
- Operating system
- Steps to reproduce
- Any relevant logs

Command Cheat Sheet Contributing