Acquia Cloud CD troubleshooting guide

This page describes some of the approaches you can take in determining the causes of errors or other problems with Acquia Cloud CD. It includes the following sections:

Acquia Cloud CD pipelines client errors

This section describes several of the common error messages generated by the Acquia Cloud CD pipelines client locally on your computer, along with actions that you can take to resolve them.

Error Description
[RuntimeException]
No credentials found. Please configure the client.
You have not yet signed in to Acquia Cloud CD. For information about obtaining an API token to use with the pipelines configure command, see Installing the Acquia Cloud CD pipelines client. You may find it easier to connect using the Acquia Cloud CD user interface instead of the command line.
[RuntimeException]
API key not found
The Acquia Cloud API key (the n3_key line in ~/.acquia/pipelines/credentials) that you provided to the pipelines configure command is not valid. For information about obtaining an API token to use with the pipelines configure command, see Installing the Acquia Cloud CD pipelines client.
[RuntimeException]
Signature not valid
The Acquia Cloud API key secret (the n3_secret line in ~/.acquia/pipelines/credentials) that you provided to the pipelines configure command is not valid. For information about obtaining an API token to use with the pipelines configure command, see Installing the Acquia Cloud CD pipelines client.
[RuntimeException]
The feature you are trying to access is not enabled on this application.
This Acquia subscription is not set up to use Acquia Cloud CD. To have this subscription be enabled, create a support ticket.
Request failed with status code 403: Forbidden You do not have the Execute pipelines permission for the Acquia Cloud application that you're working with. Ask an Administrator or Team lead for this application to provide you that permission, which by default, is granted to users who have been assigned the Team lead or Senior Developer role, but not to users with the Developer role. For more information, see Working with roles and permissions in the Acquia Cloud documentation.

Script failures

By default, Acquia Cloud CD prepends build scripts with set -e, which causes the script to exit immediately if any command has a non-zero exit code. You can override this behavior by including set +e in your build script.

Be aware that if you use set +e, the script does not fail when a command fails. Because of this, the script must manage its own exit strategy and exit codes.

Build errors

After an Acquia Cloud CD job is complete, the pipelines status command displays if it succeeded or failed. The output of the status command should appear similar to the following:

pipelines status

Job ID: 70daa6d7-c803-42a5-9555-169bd5917d85
Status: succeeded
Summary: Successfully completed the build task. Your deployment branch is: pipelines-build-master
Site: devcloud:mysite
VCS path: master
Submitted: 2016-08-04 18:50:43 (UTC)
Started: 2016-08-04 18:50:45 (UTC)
Finished: 2016-08-04 18:51:49 (UTC)

The Status line displays the job’s final status. Possible job statuses include the following:

  • succeeded - The job succeeded.
  • build error - Something under your control as a user needs to be fixed.
  • system failure - An internal problem occurred with Acquia Cloud CD. Contact Acquia Support to create a support ticket regarding the issue.

When an Acquia Cloud CD job fails with a build error, the Summary line provides additional information about what went wrong. Some of possible Summary lines that Acquia Cloud CD jobs are listed as follows:

  • Summary: Failed to complete the build because there is no acquia-pipelines.yml build file.

    There is no build definition file (acquia-pipelines.yml) in the repository. You may have forgotten to add your build definition file with git commit or you may have forgotten to git push it.

  • Summary: Failed to parse the <code>acquia-pipelines.yml file.

    The build definition file contains a syntax error. You can use a YAML validator (such as http://www.yamllint.com/) to determine if there are any errors with your your build definition file.

  • Summary: Disk usage exceeded.

    Your job could not complete because it attempted to use more disk space than was allowed.

  • Summary: The SSH key named "my-key" cannot be used because it requires a password.

    The SSH key in your build definition file is encrypted with a password. You can either:

    • Create a new SSH key without a password. For example, use the command ssh-keygen -t rsa ~/.ssh/pipelines.
    • Remove the password from the current key. For example, use the command ssh-keygen -p -f ~/.ssh/id_rsa to remove the password from the file ~/.ssh/id_rsa.

    In either case, you will need to re-add the SSH key to your build definition file with the pipelines encrypt command.

  • Summary: The SSH key named "my-key" is not a valid SSH private key.

    The SSH key in your build definition file is not an SSH key. You may have provided bad data to the pipelines encrypt command when you added it. The correct command to add an SSH key to your build definition file is cat ~/.ssh/[name_of_key_file] | pipelines encrypt - --add ssh-keys.my-key.

  • Summary: Failed to execute the build script.

    A command executed by your build definition file failed. Run the pipelines logs command to see the job output to identify what happened. Adding the set -e command to the beginning of a script that is failing will cause it to display each command before it is executed, helping you to determine which command is failing.

Composer errors

One common error generated by the Composer program is as follows:

Loading composer repositories with package information
Failed to clone the [email protected]:[repo_name].git repository, try running in interactive mode so that you can enter your GitHub credentials

In this case, Composer was unable to retrieve the GitHub repository repo_name. This may indicate that the repository requires credentials to allow access. Add an SSH key that has access to the repository to your build definition file using the pipelines encrypt command.

GitHub issues

If you encounter an error running pipelines init-github:

Ensure that you can view the GitHub Webhooks page for the repository:

  1. Sign in to GitHub.
  2. Go to your repository, and then click Settings.
  3. In the menu on the left side, click Webhooks.

If you cannot view the Webhooks page, you may not have the necessary permissions in GitHub. Contact your organization's GitHub administrator for access.

Another possible cause is that you may have used an incorrect GitHub personal access token. In GitHub, you can revoke your old personal access token, create a new one, and then try again to run pipelines init-github.

Key issues

If you cannot connect to external resources, such as GitHub, but your GitHub permissions are correct, use the following procedure to test your SSH key:

  1. Determine if the encrypted file in your acquia-pipelines.yml file can access your GitHub repo with the following command:

    ssh -i [/path/to/key] -vvv [email protected]

    The -vvv switch forces verbose output, which can indicate if GitHub accepted your SSH key.

  2. Confirm if your SSH key requires a passphrase because it is encrypted. Although newer encrypted SSH keys are indistinguishable from non-encrypted keys, use the following command to test older SSH keys:

    head -n2 /path/to/key

    After you execute the command, review its output, which will appear similar to the following:

    -----BEGIN RSA PRIVATE KEY-----
    Proc-Type: 4,ENCRYPTED

Examining the logs

The pipelines logs command returns the log entries for the application ID and job ID that you specify. The log entries include standard output and standard error from the job. To run the logs command, obtain your application ID and job ID, which can be found in the output of the start command.

The logs command has the following format:

pipelines logs <application_id> <job_id>

The log output will appear similar to the following:

Log messages for build job b33e87f1-1a53-4f29-afad-bc7d3290b603:
==============================================================
2016-08-31 08:03:36                                                        INFO
--------------------------------------------------------------------------------
The task has been added.
==============================================================
2016-08-31 08:03:37                                                        INFO
--------------------------------------------------------------------------------
The task has started.
==============================================================
2016-08-31 08:05:18                                                        INFO
--------------------------------------------------------------------------------
Successfully executed the build script. Output:
Starting local build...
Build file: /mnt/tmp/local.prod/.decoded.yml
Source: /mnt/tmp/local.prod/buildsteps
Target: /mnt/tmp/local.prod/buildsteps
Beginning to build /mnt/tmp/local.prod/buildsteps/mybuilddir/d7.make.       [ok]
drupal cloned from http://git.drupal.org/project/drupal.git.                [ok]
Checked out tag 7.50.                                                       [ok]
drupal patched with 872999-9.patch.                                         [ok]
==============================================================
2016-08-31 08:05:19                                                        INFO
--------------------------------------------------------------------------------
Workspace status:
AM docroot
R  d7.make -> mybuilddir/d7.make
==============================================================
2016-08-31 08:05:34                                                        INFO
--------------------------------------------------------------------------------
Successfully completed the build task.
==============================================================

Terminating a job

You can voluntarily terminate a job that is in progress. You might do this if the job seems stuck and unable to complete on its own, or if you realize there is a problem with the job that you need to fix. To terminate a job, use the terminate-job command:

pipelines terminate-job [job ID]

The terminate-job command terminates the most recent job, if it has not yet completed. It has an optional argument, which is the job ID, which you can use if you want to terminate a job other than the most recently started one. You can get the job ID from the pipelines status command or from the output of the pipelines start command.

Contact supportStill need assistance? Contact Acquia Support