Troubleshooting & FAQs

This page captures common CICD issues reported by users and the quickest ways to debug them. Questions are grouped by topic.

Logging and debugging

How can I increase log verbosity for debugging?

Set LOG_LEVEL in your driver file before running deployment:

os.environ["LOG_LEVEL"] = "1"

Supported values:

• 1: Basic logs
• 2: More detailed logs
• 3: Most verbose logs for deep debugging

If you need more details, increase this value and re-run the pipeline.

note

Higher log levels can include sensitive information in logs. Use elevated verbosity only for debugging and avoid sharing verbose logs broadly.

How can I save logs to a file automatically?

Enable log file output:

os.environ["LOG_FILE"] = "true"

When enabled, CICD generates the log file amorphic_cicd.log, and if it is run in CICD infrastructure, this file is automatically uploaded to the S3 artifact bucket at <branch-name>/logs/<code-build-number>/amorphic_cicd.log, which is easier to inspect than long UI log streams.

important

Set logging environment variables before importing ResourceManager.

If LOG_LEVEL and LOG_FILE are set after the import, initialization may already use default values.

import os

os.environ["LOG_LEVEL"] = "1"
os.environ["LOG_FILE"] = "true"

from amorphiccicdutils import ResourceManager

CloudWatch or CodeBuild is slow or unusable when logs are very large. What should I do?

When pipeline logs are very large, CloudWatch and CodeBuild consoles may struggle to render them. As part of recent CI/CD infrastructure enhancements, logs can be uploaded automatically to S3 by enabling:

os.environ["LOG_FILE"] = "true"

If this was not enabled and UI logs are hard to load, use the script below to download logs directly from CloudWatch.

import boto3


def fetch_latest_log_stream(log_group_name):
    client = boto3.client("logs")

    response = client.describe_log_streams(
        logGroupName=log_group_name,
        orderBy="LastEventTime",
        descending=True,
        limit=1,
    )

    streams = response.get("logStreams", [])
    if not streams:
        raise Exception("No log streams found")

    return streams[0]["logStreamName"]


def download_logs(log_group_name, log_stream_name, output_file):
    client = boto3.client("logs")

    next_token = None

    with open(output_file, "w") as f:
        while True:
            if next_token:
                response = client.get_log_events(
                    logGroupName=log_group_name,
                    logStreamName=log_stream_name,
                    nextToken=next_token,
                    startFromHead=True,
                )
            else:
                response = client.get_log_events(
                    logGroupName=log_group_name,
                    logStreamName=log_stream_name,
                    startFromHead=True,
                )

            events = response.get("events", [])

            for event in events:
                f.write(event["message"] + "\n")

            new_token = response.get("nextForwardToken")

            # Stop when token does not change
            if new_token == next_token:
                break

            next_token = new_token


if __name__ == "__main__":
    import sys

    if len(sys.argv) < 2:
        print("Usage: python fetch_logs.py <log-group-name> [output-file]")
        sys.exit(1)

    log_group_name = sys.argv[1]
    output_file = sys.argv[2] if len(sys.argv) > 2 else "logs.txt"

    print(f"Fetching latest log stream from: {log_group_name}")

    log_stream_name = fetch_latest_log_stream(log_group_name)
    print(f"Latest log stream: {log_stream_name}")

    download_logs(log_group_name, log_stream_name, output_file)

    print(f"Logs saved to {output_file}")

Run:

python fetch_logs.py </aws/codebuild/log_group_name> logs.txt

Resource naming

Hyphens are not allowed in some CICD logical names, and underscores are not allowed in some Amorphic names. What should I use?

We follow a strict logical resource naming standard similar to CloudFormation.

• Keep CICD logical names simple and portable.
• Avoid special characters in logical names (especially hyphens and underscores).
• Use alphanumeric names with clear prefixes (for example, rDomain, rDatasetSales).

Some Amorphic resources allow hyphens in actual resource names, and some support underscores. To keep templates consistent across all resource types, avoid special characters in logical resource names.

Shared libraries

Are zip files supported in shared libraries?

Yes. Amorphic CICD supports uploading zip files for shared libraries. There is no strict file-type validation in CICD for shared library artifacts. If the file type is supported by Amorphic, CICD supports uploading it as well.

Pipeline runs and timeouts

The pipeline timed out unexpectedly, logs look clean, and there is no clear failure. What should I check?

If the pipeline times out without a clear application-level failure in logs, investigate the AWS side (especially CodeBuild execution details and timeout settings).

The default CodeBuild timeout is 5 hours. If builds are consistently timing out near that limit, review and tune build timeout settings and check AWS service-side behavior.