Migration update
qmims has been migrated from Amazon Q CLI to Kiro CLI. These docs reflect the current install, authentication, and command workflows.
Troubleshooting
Common setup, authentication, and workflow issues with qmims and Kiro CLI
qmims depends on Kiro CLI for generation and editing workflows. Most runtime issues fall into one of four categories: installation problems, authentication problems, file/path issues, or template/configuration mistakes.
First things to verify
node --version kiro-cli --version kiro-cli whoami
Common Issues
Debugging with Verbose Output
When a command fails unexpectedly, add --verbose to see more detail about what qmims is doing before it hands off to Kiro.
qmims generate --verbose qmims edit --verbose
Verbose output is useful for checking:
- Whether qmims resolved the expected target path
- Whether Kiro availability and auth checks succeeded
- Which mode or template qmims selected
- Whether the issue happens before or during Kiro execution
Helpful debugging sequence
kiro-cli whoami kiro-cli doctor qmims generate --dry-run qmims generate --verbose
Dependency Checklist
If you are not sure whether the environment is ready, verify each dependency explicitly:
# Check Node.js node --version # Check Kiro CLI kiro-cli --version # Check Kiro authentication kiro-cli whoami # Check qmims qmims --version
- Node.js version 18 or later
- Kiro CLI installed
- Kiro CLI authenticated or `KIRO_API_KEY` configured
- qmims installed and available on PATH
Getting Help
For command-specific usage, use built-in help:
qmims --help qmims generate --help qmims edit --help qmims config --help qmims templates --help
For setup walkthroughs, see the Installation guide. For command behavior details, use the Command Reference.
Common Error Messages
| Error Message | Likely Cause | Typical Fix |
|---|---|---|
| Kiro CLI is not installed | Kiro CLI is missing from the system | Install Kiro CLI and verify with kiro-cli --version |
| Kiro CLI is installed but you are not signed in | Auth session missing or expired | Run kiro-cli login and confirm with kiro-cli whoami |
| No embedded instructions found | The target Markdown file has no <!-- qmims: ... --> comments | Add embedded qmims instructions to the file |
| Template not found | Wrong template name or missing custom template | List templates or add the custom template first |
| EACCES: permission denied | Filesystem or installation permissions issue | Fix permissions or use a writable environment |
| command not found: qmims | qmims is not installed globally or not on PATH | Reinstall qmims and verify the global bin path |
Still stuck?
- the exact command you ran
- the full error output
- the result of
kiro-cli whoami - the result of
kiro-cli doctor - the verbose output from qmims
Then open an issue on the qmims GitHub repository.