Troubleshooting
This guide helps you diagnose and resolve common issues with the GrantFlow CLI. For each problem, we explain the symptoms, likely causes, and step-by-step solutions.
Authentication Issues
Authentication problems are the most common issues you'll encounter when using the CLI. These typically manifest as errors when running commands that require API access.
Device Code Login Fails
Symptoms: When you run grantflow login, you receive an error after entering the device code in your browser, or the CLI times out waiting for authentication.
Common Causes:
The tenant ID or client ID in your configuration doesn't match your GrantFlow environment. Your Azure AD administrator may have changed application permissions without updating your configuration. Network connectivity issues prevent the CLI from reaching Azure AD or GrantFlow APIs.
Solutions:
First, verify your configuration values are correct:
grantflow config view
Compare the tenant ID and client ID to the values your administrator provided. If they don't match, update your configuration file at ~/.grantflow/config.yaml or set the correct environment variables.
Next, test network connectivity to Azure AD:
curl -I https://login.microsoftonline.com
If this fails, check your network proxy settings or firewall rules. Some corporate networks require proxy configuration.
Finally, try authenticating again with debug logging enabled to see detailed error messages:
grantflow login --debug
The debug output shows the exact error from Azure AD, which often points to permission or configuration issues.
Token Expired or Invalid
Symptoms: Commands that worked previously now fail with authentication errors like "401 Unauthorized" or "invalid token."
Common Causes:
Your cached token has expired and can't be refreshed automatically. The refresh token itself has expired (typically after 90 days). Your administrator revoked the application's permissions or deleted the app registration.
Solutions:
Clear your token cache and re-authenticate:
grantflow logout
grantflow login
This forces a fresh authentication flow and caches new tokens. If login succeeds, your previous tokens were simply expired.
If you still can't authenticate, verify the CLI application is still registered in Azure AD and has the correct API permissions. Contact your GrantFlow administrator to confirm the application configuration.
Multi-Factor Authentication Required
Symptoms: During device code login, you're prompted for additional authentication factors that fail or time out.
Common Causes:
Your organization requires MFA for all authentications, but you're having trouble completing the additional factor (SMS, authenticator app, etc.). The device code flow times out during MFA prompts.
Solutions:
Ensure you have access to your MFA device (phone, authenticator app) before running grantflow login. The device code flow gives you several minutes to complete all authentication steps, including MFA.
If MFA consistently times out, try using a faster second factor like an authenticator app instead of SMS. You can also request an extended timeout from your Azure AD administrator by adjusting the device code flow timeout in the app registration.
API Connectivity Issues
Problems reaching the GrantFlow API prevent commands from executing correctly.
Connection Refused or Timeout
Symptoms: Commands fail with network errors like "connection refused," "timeout," or "no route to host."
Common Causes:
The API URL in your configuration is incorrect or unreachable. Network firewalls block access to the GrantFlow API. DNS resolution fails for the API hostname.
Solutions:
Verify the API URL is correct:
grantflow config view
For GrantFlow's cloud service, the URL should be https://api.grantflow.cloud. Self-hosted installations use their own domain.
Test basic connectivity to the API:
curl -I https://api.grantflow.cloud/health
If this fails, check your network settings. You may need to configure a proxy or request firewall exceptions from your IT department.
If you're using a self-hosted GrantFlow instance, verify the hostname resolves correctly:
nslookup api.your-domain.com
SSL/TLS Certificate Errors
Symptoms: Commands fail with certificate validation errors or "unable to verify certificate" messages.
Common Causes:
Self-signed certificates used in development environments. Corporate proxy performing SSL inspection. System certificate store missing required root certificates.
Solutions:
For development environments with self-signed certificates, you can temporarily bypass certificate validation (not recommended for production):
# This is insecure - only use in development
export GRANTFLOW_INSECURE_SKIP_VERIFY=true
For corporate proxies performing SSL inspection, install your organization's root certificate in your system's certificate store.
On macOS:
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/certificate.crt
On Linux:
sudo cp /path/to/certificate.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
Contact your IT department for the correct certificate file if you don't have it.
Permission and Authorization Issues
These problems occur when your user account lacks necessary permissions for the requested operation.
Forbidden (403) Errors
Symptoms: Commands return "403 Forbidden" or "insufficient permissions" errors, even though you're successfully authenticated.
Common Causes:
Your user account doesn't have the required role for the operation. For admin commands, you need the administrator role. For activation approval, you need approver assignment.
Solutions:
Verify your role assignments by checking in the GrantFlow web interface or asking your administrator. Regular users can request activations, check out accounts, and view their own audit trail. Administrators can manage connectors, agents, jobs, and create roles.
If you believe you should have access but don't, contact your GrantFlow administrator to verify your role assignments and permissions.
Resource Not Found (404) Errors
Symptoms: Commands return "404 Not Found" when accessing specific resources by ID.
Common Causes:
The resource ID is incorrect or misspelled. The resource exists but belongs to a different tenant. The resource was deleted since you last saw it.
Solutions:
Double-check the resource ID you're using. List available resources first to find the correct ID:
# Verify role ID
grantflow roles list
# Verify account ID
grantflow accounts list
# Verify activation ID
grantflow activations list
Copy and paste IDs rather than typing them manually to avoid typos.
If you're certain the ID is correct but still get 404 errors, the resource may be tenant-specific and not visible to your account. Verify you're using the correct tenant configuration.
Command-Specific Issues
Certain commands have unique failure modes worth understanding.
Activation Request Fails
Symptoms: grantflow activations request returns an error instead of creating the request.
Common Causes:
The requested duration exceeds the role's maximum allowed duration. The justification is missing or too short. You're not eligible to activate the specified role.
Solutions:
Check the role's maximum duration:
grantflow roles get <role-id>
Ensure your --duration parameter doesn't exceed the maxDuration value. If it does, reduce your requested duration.
Always provide a clear, meaningful justification using the --reason flag:
grantflow activations request role-prod-dba \
--duration 120 \
--reason "Emergency database performance investigation - incident INC0012345"
Verify you're eligible for the role by checking if it appears in your roles list:
grantflow roles list | grep role-prod-dba
If the role doesn't appear, you're not eligible. Contact your administrator to request assignment.
Checkout Fails
Symptoms: grantflow accounts checkout returns an error or times out.
Common Causes:
The account is disabled or undergoing maintenance. The checkout duration exceeds policy limits. Approval is required but pending.
Solutions:
Check the account's status:
grantflow accounts get <account-id>
Verify the enabled field is true. If false, the account is temporarily unavailable.
Ensure your requested duration doesn't exceed the maxCheckoutMinutes value. Reduce your --duration parameter if necessary.
Some accounts require approval before checkout. If your request seems to hang, check the web interface to see if approval is pending.
Audit List Returns No Results
Symptoms: grantflow audit list returns an empty result set when you expect to see events.
Common Causes:
Your filters are too restrictive and exclude all events. The requested events are outside the retention period. You lack permission to view audit events.
Solutions:
Try listing without filters first to confirm events exist:
grantflow audit list --limit 100
If this returns results, your filters are the problem. Gradually add filters one at a time to identify which one excludes your desired events.
Check your tenant's audit retention policy. Events older than the retention period are automatically purged.
Verify you have permission to view audit events. Most users can see their own actions, but viewing organization-wide audit logs typically requires administrator privileges.
Configuration Issues
Problems with configuration files or settings can prevent the CLI from functioning correctly.
Configuration File Not Found
Symptoms: The CLI behaves as if no configuration file exists, using default values or environment variables instead.
Common Causes:
The configuration file doesn't exist at the expected location. File permissions prevent the CLI from reading it. The file path is incorrect.
Solutions:
Verify the file exists:
ls -la ~/.grantflow/config.yaml
If the file doesn't exist, create it following the Configuration Guide.
Check file permissions:
chmod 600 ~/.grantflow/config.yaml
If you're using a custom configuration path, ensure you specify it correctly:
grantflow roles list --config /path/to/your/config.yaml
Invalid YAML Syntax
Symptoms: The CLI fails to parse your configuration file and shows YAML parsing errors.
Common Causes:
Indentation errors in the YAML file. Missing or extra quotes. Special characters not properly escaped.
Solutions:
Validate your YAML syntax using a validator:
python3 -c "import yaml; print(yaml.safe_load(open(os.path.expanduser('~/.grantflow/config.yaml'))))"
Common YAML mistakes to check:
- Use spaces for indentation, never tabs
- Surround URLs in quotes if they contain special characters
- Keep consistent indentation levels (usually 2 spaces per level)
Here's a correct example:
api_url: "https://api.grantflow.cloud"
tenant_id: "5abfdf65-694b-4c35-9b9b-e65af70c8306"
client_id: "32654b34-df24-4a9b-9261-27f37a66bff9"
output: "table"
Debug Mode
When troubleshooting any issue, enable debug mode to see detailed diagnostic information:
grantflow roles list --debug
Debug output includes:
- HTTP requests and responses
- Authentication token metadata (not the token itself)
- Configuration values being used
- Detailed error messages and stack traces
This information helps you identify exactly where problems occur and provides useful context when contacting support.
Debug output may contain sensitive information like API endpoints and user IDs. Sanitize this information before sharing it publicly.
Getting Help
If you've tried these troubleshooting steps and still can't resolve your issue:
Check Documentation
Review the relevant command documentation to ensure you're using the correct syntax and parameters:
- Authentication Commands
- Role Commands
- Activation Commands
- Account Commands
- Audit Commands
- Admin Commands
Contact Support
Reach out to GrantFlow support with the following information:
- The exact command you ran
- The complete error message
- Output from
grantflow --version - Output from
grantflow config view(with sensitive values redacted) - Debug output if applicable (sanitized)
Email support at support@grantflow.cloud.
Check System Status
If multiple users are experiencing issues simultaneously, check the GrantFlow status page for ongoing incidents or maintenance windows at status.grantflow.cloud.
Related Topics
- Configuration Guide - Detailed configuration instructions
- Installation & Setup - Initial installation and configuration
- Authentication Commands - Managing authentication