troubleshooting
Use when acli commands fail, return unexpected errors, authentication breaks, or the CLI behaves unexpectedly.
How do I install this agent skill?
npx skills add https://github.com/acquia/acquia-skills --skill troubleshootingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides legitimate troubleshooting guidance for the Acquia CLI tool. It contains standard shell commands for fixing environment issues, managing authentication, and diagnosing connectivity, all directed at official vendor resources.
- Socketpass
No alerts
- Snykfail
Risk: CRITICAL · 2 issues
What does this agent skill do?
Troubleshooting Acquia CLI
Use when:
- Diagnosing acli authentication failures
- Resolving command errors or unexpected output
- Collecting information before contacting support
General Issues
"Command not found: acli"
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
"Permission denied" when running acli
Cause: The binary isn't executable.
Solution:
chmod +x "$(command -v acli)"
acli --version
"acli: command not found" after updating
Cause: Update didn't complete or PATH changed.
Solution:
Reinstall per Getting Started, then check which copy your shell resolves:
command -v acli
acli --version
TLS / certificate errors during download
Symptoms: curl or acli fails with a certificate/SSL error.
Cause: Usually a corporate proxy that intercepts TLS (e.g. Zscaler) with its own root CA.
Solutions:
- Switch to the other install option once (see Getting Started). Don't loop.
- If that fails too, stop and tell the user their network's TLS inspection is blocking the
download. Don't try CA bundle or
.inioverrides yourself. For the user: a CA bundle that includes the proxy's root CA (from IT) fixes this:export CURL_CA_BUNDLE=/path/to/corp-ca-bundle.pem(curl downloads) andexport SSL_CERT_FILE=/path/to/corp-ca-bundle.pem(native acli). - If the network blocks
github.com/release-assets.githubusercontent.comoutright, ask an admin to allow them.
"Deprecated: ..." warnings break JSON output
<a id="deprecated-warnings-break-json-output"></a>
Symptoms: Lines starting Deprecated: appear before acli's JSON, so parsing fails. Seen
with the PHAR on PHP 8.5.
Solutions:
- Use the native binary (see Getting Started).
- Or hide deprecation notices when running the PHAR:
php -d error_reporting='E_ALL & ~E_DEPRECATED' -d display_errors=stderr "$(command -v acli)" <command> - When parsing, read stdout only and skip anything before the first
{or[.
Authentication Issues
auth:login --no-interaction fails asking for an API key
Symptoms: Already authenticated as ... (API key), then
Enter your Cloud Platform API key (option -k, --key) and a non-zero exit.
Cause: An API key is already stored. acli asks Sign in with device code instead? with a
default of no; --no-interaction takes that default and falls through to the key prompt.
Solution: with an API key stored, drop -n and answer the prompt with one piped y:
# Run in the background; read the activation URL and code.
printf 'y\n' | ACLI_NO_TELEMETRY=true acli auth:login
Only this case takes the piped y. With nothing stored or a device session, use
ACLI_NO_TELEMETRY=true acli -n auth:login and pipe nothing; see
Agents and scripts. acli stays interactive
with a piped stdin unless -n is passed, and nothing in it reads SHELL_INTERACTIVE.
Switching to device code deactivates the stored API key: acli keeps it in the config file but stops using it, and only acli auth:login --use-legacy-auth makes it active again. Scripts that rely on that key stop authenticating, so tell the user before you sign in this way. Don't pipe yes into auth:login: if device code fails, it
answers the API key fallback prompts as well and loops forever on Value "y" is invalid, and
it can open a browser on the user's machine. Then run acli api:accounts:find to confirm the
active identity is the one you expect.
"Error: Failed to authenticate"
Cause: Your authentication token expired or isn't valid.
Solution:
# Re-authenticate
acli auth:login
# This opens your browser to authorize again
Device code sign-in fails
acli auth:login (device code) ends with one of these:
- "Authorization denied." — the sign-in was declined in the browser. Run
acli auth:loginagain and approve it. - "Code expired. Run acli login again." — nobody approved within 10 minutes. Run
acli auth:loginagain and approve sooner. - "Sign-in failed: an Acquia ID may already exist for this email address." — an
Acquia ID already exists for that email, so the sign-in couldn't create or link one. Run
acli auth:loginagain and, in the browser, sign in with that email address and password rather than through SSO/a social login.
"Error: Access Denied"
Cause: Your account doesn't have permission to access the resource.
Solutions:
-
Check you're logged in with the right account:
acli api:accounts:find -
Verify you have access in Acquia Cloud UI:
- Go to https://cloud.acquia.com
- Check if you can see the application or resource
-
Log out and back in:
acli auth:logout acli auth:login
"Invalid JSON in cloud_api.conf"
Cause: Credentials file is corrupted.
Solution:
# Find which config directory ACLI is actually using
ACLI_DIR="${ACLI_HOME:-$([ -d ~/.acquia ] && echo ~/.acquia || echo ~/.config/acquia)}"
echo "$ACLI_DIR"
# Remove the corrupted file from that directory:
rm "$ACLI_DIR/cloud_api.conf"
# Re-authenticate
acli auth:login
If both ~/.acquia/ and ~/.config/acquia/ exist on your machine with different content,
only the one ACLI_HOME resolves to (legacy ~/.acquia/ wins if present) is actually in use —
don't remove the other one without checking it first, since it may hold valid credentials
from before a config-directory change.
IDE Issues
IDE won't start
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
IDE is very slow
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"
"Access Denied" when opening 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
IDE appears deleted but still exists
Cause: The IDE is hibernated or the listing is cached.
Solution:
# Clear cache and list again
acli self:clear-caches
acli ide:list
SSH Key Issues
"Permission denied (publickey)"
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
"SSH key not found when creating IDE"
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
"Multiple SSH keys - which one to use?"
Solution:
Add to ~/.ssh/config:
Host <ide-ssh-host>
IdentityFile ~/.ssh/my_custom_key
Application & Environment Issues
"No applications found"
Cause: You don't have access to any applications yet.
Solutions:
-
Check if you're in a team:
acli api:accounts:find -
Ask your team admin to add you to an application
"Error: Application not found"
Cause: Wrong application UUID or no access.
Solutions:
-
List applications to find the right one:
acli api:applications:listMEO (V3) subscriptions:
api:applications:listreturns nothing — list your resources withacli api:v3:sites:listoracli api:v3:codebases:listinstead (see MEO Overview). -
Use the correct application:
acli ide:create --application=<correct-uuid>
Command Execution Issues
"Error: Drush command failed"
Cause: Drush error in your Drupal site.
Solutions:
-
Check Drush output for details:
acli remote:drush status -
Clear caches:
acli remote:drush cr
"Error: Could not connect to remote server"
Cause: Network connectivity or SSH key issue.
Solutions:
-
Check SSH key setup:
acli ssh-key:list -
Try verbose output for details:
acli -vvv <command>
Performance Issues
Commands taking too long
Solutions:
-
Try again (might be temporary)
-
Check internet connection:
ping acquia.com -
Try with shorter timeout:
acli <command> --no-wait
Cache causing stale data
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
Getting Help
Check your acli version
acli --version
Enable debug output
# Run any command with verbose output
acli -vvv <command>
# Save to a log file
acli -vvv <command> > debug.log 2>&1
View all help
# General help
acli --help
# List all commands
acli list
# Help for a specific command
acli <command> --help
Getting Help from Support
Before contacting support, gather info
# Your version
acli --version
# Your account info
acli api:accounts:find
# Your applications (ACE / V2). On MEO (V3), use: acli api:v3:sites:list
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
Contact Acquia Support
- Support Portal: https://acquia.my.site.com/s/
- GitHub Issues: https://github.com/acquia/cli/issues
- Discussions: https://github.com/acquia/cli/discussions
Common Error Messages
| 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 |
Advanced Troubleshooting
Check API responses
# See what the API is returning
acli -vvv <command> 2>&1 | grep -A 5 "Response:"
Reset all configuration
# CAUTION: This clears everything. Resolve the directory ACLI actually uses first:
ACLI_DIR="${ACLI_HOME:-$([ -d ~/.acquia ] && echo ~/.acquia || echo ~/.config/acquia)}"
echo "$ACLI_DIR"
# Then remove it:
rm -rf "$ACLI_DIR"
# Re-authenticate
acli auth:login
Best Practices
- Stay updated — Run
acli self:updateregularly; many errors are fixed in newer versions. - Check authentication first — Run
acli api:accounts:findbefore blaming other commands. - Use verbose mode — Add
-vvvto any failing command to see detailed error output.
Still stuck? Contact Acquia Support
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/acquia/acquia-skills/troubleshooting">View troubleshooting on skillZs</a>