skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
acquia/acquia-skills136 installs

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 troubleshooting
view source ↗

Is 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:

  1. Switch to the other install option once (see Getting Started). Don't loop.
  2. If that fails too, stop and tell the user their network's TLS inspection is blocking the download. Don't try CA bundle or .ini overrides 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) and export SSL_CERT_FILE=/path/to/corp-ca-bundle.pem (native acli).
  3. If the network blocks github.com / release-assets.githubusercontent.com outright, 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:login again and approve it.
  • "Code expired. Run acli login again." — nobody approved within 10 minutes. Run acli auth:login again 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:login again 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:

  1. Check you're logged in with the right account:

    acli api:accounts:find
    
  2. Verify you have access in Acquia Cloud UI:

  3. 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:

  1. Try restarting IDE services:

    acli ide:service-stop
    acli ide:service-start
    
  2. Check IDE status:

    acli ide:info
    
  3. Wait if newly created: New IDEs take 2-3 minutes to start. Check again in a minute.

  4. Try creating a new IDE:

    acli ide:create
    

IDE is very slow

Causes: Hibernation waking, stuck processes, or resource limits

Solutions:

  1. Wait if waking from hibernation: IDEs waking take 30-60 seconds. Be patient.

  2. Clear Drupal caches:

    acli remote:drush cr
    
  3. Restart IDE:

    acli ide:service-restart
    
  4. 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:

  1. Verify SSH key exists:

    ls -la ~/.ssh/id_rsa
    
  2. If not, create one:

    acli ssh-key:create
    
  3. Check permissions (must be 600):

    chmod 600 ~/.ssh/id_rsa
    
  4. 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:

  1. Check if you're in a team:

    acli api:accounts:find
    
  2. Ask your team admin to add you to an application

"Error: Application not found"

Cause: Wrong application UUID or no access.

Solutions:

  1. List applications to find the right one:

    acli api:applications:list
    

    MEO (V3) subscriptions: api:applications:list returns nothing — list your resources with acli api:v3:sites:list or acli api:v3:codebases:list instead (see MEO Overview).

  2. 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:

  1. Check Drush output for details:

    acli remote:drush status
    
  2. Clear caches:

    acli remote:drush cr
    

"Error: Could not connect to remote server"

Cause: Network connectivity or SSH key issue.

Solutions:

  1. Check SSH key setup:

    acli ssh-key:list
    
  2. Try verbose output for details:

    acli -vvv <command>
    

Performance Issues

Commands taking too long

Solutions:

  1. Try again (might be temporary)

  2. Check internet connection:

    ping acquia.com
    
  3. 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


Common Error Messages

ErrorMeaningSolution
"Error: Access Denied"You don't have permissionCheck account access, team membership
"Command not found"Binary not in PATHCheck installation, verify PATH
"Failed to authenticate"Token expired or invalidRe-run acli auth:login
"SSH Key not found"IDE needs SSH keyCreate key with acli ssh-key:create
"IDE not starting"IDE provisioning slow or failedWait 2-3 min, restart, or create new
"Permission denied (publickey)"SSH key issueVerify key setup: acli ssh-key:list
"No applications found"No team accessAsk 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

  1. Stay updated — Run acli self:update regularly; many errors are fixed in newer versions.
  2. Check authentication first — Run acli api:accounts:find before blaming other commands.
  3. Use verbose mode — Add -vvv to any failing command to see detailed error output.

Still stuck? Contact Acquia Support

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>