Menu
Use when acli commands fail, return unexpected errors, authentication breaks, or the CLI behaves unexpectedly.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | troubleshooting |
| description | Use when acli commands fail, return unexpected errors, authentication breaks, or the CLI behaves unexpectedly. |
| license | Proprietary |
| compatibility | acli>=2.x |
| metadata | {"category":"troubleshooting","author":"Acquia","version":"1.0.0","tags":"acli, acquia-cloud, troubleshooting, errors, authentication","software_requirements":"acli>=2.x"} |
Use when:
Cause: The binary isn't in your system PATH.
Solutions:
# Check if it's installed
which acli
# If nothing, add to PATH
export PATH="/usr/local/bin:$PATH"
# Test
acli --version
# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Cause: The binary isn't executable.
Solution:
chmod +x /usr/local/bin/acli
acli --version
Cause: Update didn't complete or PATH changed.
Solution:
# Reinstall
curl -fsSL https://github.com/acquia/cli/releases/latest/download/acli \
-o /usr/local/bin/acli
chmod +x /usr/local/bin/acli
# Verify
acli --version
Cause: Your authentication token expired or isn't valid.
Solution:
# Re-authenticate
acli auth:login
# This opens your browser to authorize again
Cause: Your account doesn't have permission to access the resource.
Solutions:
Check you're logged in with the right account:
acli auth:me
Verify you have access in Acquia Cloud UI:
Log out and back in:
acli auth:logout
acli auth:login
Cause: Credentials file is corrupted.
Solution:
# Remove the corrupted file
rm -rf ~/.acquia/cloud_api/
# Re-authenticate
acli auth:login
Symptoms: IDE shows "Starting..." indefinitely or won't load.
Solutions:
Try restarting IDE services:
acli ide:service-stop
acli ide:service-start
Check IDE status:
acli ide:info
Wait if newly created: New IDEs take 2-3 minutes to start. Check again in a minute.
Try creating a new IDE:
acli ide:create
Causes: Hibernation waking, stuck processes, or resource limits
Solutions:
Wait if waking from hibernation: IDEs waking take 30-60 seconds. Be patient.
Clear Drupal caches:
acli remote:drush cr
Restart IDE:
acli ide:service-restart
Create a fresh IDE:
acli ide:create --label "Fresh IDE"
Cause: Your SSH key isn't set up.
Solution:
# Create an SSH key
acli ssh-key:create
# Try accessing IDE again
acli ide:open
Cause: The IDE is hibernated or the listing is cached.
Solution:
# Clear cache and list again
acli self:clear-caches
acli ide:list
Cause: SSH key isn't set up or not used correctly.
Solutions:
Verify SSH key exists:
ls -la ~/.ssh/id_rsa
If not, create one:
acli ssh-key:create
Check permissions (must be 600):
chmod 600 ~/.ssh/id_rsa
Verify key is added to Acquia account:
acli ssh-key:list
Cause: IDE creation requires an SSH key for secure access.
Solution:
# Create SSH key first
acli ssh-key:create
# Then create IDE
acli ide:create
Solution:
Add to ~/.ssh/config:
Host ide-*.ides.acquia.com
IdentityFile ~/.ssh/my_custom_key
Cause: You don't have access to any applications yet.
Solutions:
Check if you're in a team:
acli auth:me
Ask your team admin to add you to an application
Cause: Wrong application UUID or no access.
Solutions:
List applications to find the right one:
acli api:applications:list
Use the correct application:
acli ide:create --application=<correct-uuid>
Cause: Drush error in your Drupal site.
Solutions:
Check Drush output for details:
acli remote:drush status
Clear caches:
acli remote:drush cr
Cause: Network connectivity or SSH key issue.
Solutions:
Check SSH key setup:
acli ssh-key:list
Try verbose output for details:
acli -vvv <command>
Solutions:
Try again (might be temporary)
Check internet connection:
ping acquia.com
Try with shorter timeout:
acli <command> --no-wait
Cause: CLI caches API responses.
Solutions:
# Clear cache
acli self:clear-caches # aliases: acli cc, acli cr
# Try the command again
acli <command>
# Or run with --no-cache if supported
acli <command> --no-cache
acli --version
# Run any command with verbose output
acli -vvv <command>
# Save to a log file
acli -vvv <command> > debug.log 2>&1
# General help
acli --help
# List all commands
acli list
# Help for a specific command
acli <command> --help
# Your version
acli --version
# Your account info
acli auth:me
# Your applications
acli api:applications:list
# Your IDEs
acli ide:list
# Your SSH keys
acli ssh-key:list
# Debug output of the problem command
acli -vvv <command> 2>&1 | tee debug.log
| Error | Meaning | Solution |
|---|---|---|
| "Error: Access Denied" | You don't have permission | Check account access, team membership |
| "Command not found" | Binary not in PATH | Check installation, verify PATH |
| "Failed to authenticate" | Token expired or invalid | Re-run acli auth:login |
| "SSH Key not found" | IDE needs SSH key | Create key with acli ssh-key:create |
| "IDE not starting" | IDE provisioning slow or failed | Wait 2-3 min, restart, or create new |
| "Permission denied (publickey)" | SSH key issue | Verify key setup: acli ssh-key:list |
| "No applications found" | No team access | Ask admin to add you to team |
# See what the API is returning
acli -vvv <command> 2>&1 | grep -A 5 "Response:"
# CAUTION: This clears everything
rm -rf ~/.acquia
# Re-authenticate
acli auth:login
acli self:update regularly; many errors are fixed in newer versions.acli auth:me before blaming other commands.-vvv to any failing command to see detailed error output.Still stuck? Contact Acquia Support
Use when user asks about updating outdated Drupal packages, upgrading Drupal core minor or patch versions, updating contrib modules, or resolving composer version conflicts.
Use when user asks about fixing security vulnerabilities, composer audit failures, vulnerable Drupal packages, or CVE advisories in a Drupal codebase.
Use when user wants to update Drupal dependencies and deploy the changes to an Acquia environment, optionally triggering a pipeline build. Chains drupal-maintenance, acli, and pipelines-cli skills.
Use when listing Acquia Cloud applications, linking or unlinking a local repo to an application, opening an app in browser, checking VCS/branch deployment status, or exporting a site archive.
Use when setting up a new Code Studio (GitLab CI/CD) project, changing PHP version in Code Studio builds. NOT for checking pipeline job status — use pipelines-cli-pipeline-operations for that.
Use when listing, creating, deleting, or mirroring Cloud environments, managing CDEs, deploying code to an environment, or checking environment status.