Overview

A well-crafted support request can mean the difference between a resolution in hours versus days. Here's how to provide everything our support team needs to help you quickly.

Quick Checklist

Before submitting your support request, verify you've included:

Clear problem statement (what should happen vs. what actually happens)
Impact statement (why this matters)
Failing build link (specific job)
Successful build link (before the issue)
Complete error messages (full text)
Timeline with specific dates/times
What changed recently
Screenshots/logs (if they add value)

1. Write a Clear Problem Statement (Most Important!)

This is the foundation of your support request. A strong problem statement answers three questions:

What Should Be Happening?

Be specific about the expected behavior.

Weak: "My build isn't working"

Strong: "My deployment job should push a Docker image to AWS ECR and deploy it to our production ECS cluster"

What Is Actually Happening?

Explain the actual behavior and where things go wrong.

Weak: "It fails"

Strong: "The build completes the Docker push successfully, but fails during the ECS deployment step with an authentication error"

What Impact Is This Having?

Help us understand urgency and business impact. You can use the following to help guide you:

Be specific about which job and step is failing
Describe what you observe, not what you think is wrong
State both expected and actual outcomes
Include relevant constraints (e.g., "only on main branch," "only for external PRs")

Problem Statement Example

Poor:

"CircleCI won't let me deploy. It's been broken since yesterday."

Excellent:

"Our production deployment workflow is failing at the 'deploy-to-kubernetes' step. Expected behavior: application container deploys to our GKE cluster after passing tests. Actual behavior: job fails with a kubectl authentication error. This began January 28th at 2:00 PM EST and is blocking all production releases. Prior to this, deployments were completing successfully 3-4 times per day."

2. Provide Relevant Build Links

Include a Failing Build

Link to the specific failing job, not just the workflow:

https://app.circleci.com/pipelines/github/your-org/your-repo/123/workflows/abc-def/jobs/456

Include a Successful Build

Provide a link from before the issue began. This comparison helps us identify what changed.

Include Multiple Builds When

The issue is intermittent (show 2-3 failing and 1-2 successful builds)
Different jobs are affected differently
You've tried different approaches to fix it

3. Share Complete Error Messages

Copy and paste the full error text—don't paraphrase.

Inadequate: "I get a permission error"

Complete:

[Errno 13] Permission denied: '/home/circleci/.aws/credentials'
Traceback (most recent call last):
  File "/usr/local/bin/aws", line 8, in <module>
    sys.exit(main())
Exited with code exit status 255

Include:

Error codes and stack traces
File paths and line numbers
Which step generated the error
What command was running

4. Use Screenshots and Screen Recordings Wisely

Visual information should supplement text, not replace it.

When Screenshots Help

UI issues or unexpected interface behavior
Highlighting specific sections in long logs
Configuration context (with sensitive data redacted)

Best Practices

Always include text descriptions alongside screenshots
Never share only screenshots of errors - copy the actual text too
Redact sensitive information - API keys, passwords, internal URLs
Highlight the relevant area with arrows or circles

5. Attach Relevant Log Files

Include additional logs when needed:

Application logs not captured in build output
Detailed test reports or coverage reports
Debug or verbose mode logs
External service logs (AWS, Docker, Kubernetes)

Keep logs relevant and clearly labeled.

6. Provide a Clear Timeline

Understanding when the issue started is often key to finding the solution.

Include:

When it started: "First noticed January 28, 2026 at 2:15 PM EST"
Frequency: "Every build" or "Approximately 30% of builds"
Last success: "Last successful deployment was January 27, 2026 at 6:45 PM EST" (include build link)
What changed: Config updates, dependency changes, team changes, external factors

Vague: "This started recently and happens sometimes"

Clear:

Last successful build: Jan 27, 6:45 PM EST (link: https://app.circleci.com/...)

First failure: Jan 28, 2:15 PM EST (link: https://app.circleci.com/...)

Frequency: Every build since then (15 consecutive failures)

Changes: Updated aws-cli orb from 5.3.0 to 5.4.1 on Jan 28 at 1:00 PM EST

Impact: All production deployments blocked for 24 hours

Complete Example

Subject: Production ECS deployments failing with AWS credentials permission error

Problem Statement: Our production deployment workflow should push Docker images to AWS ECR and deploy to ECS. Expected: after tests pass, deploy-production builds an image, pushes to ECR, and updates our ECS service. Actual: build fails during AWS CLI configuration with a permission error. ECR push succeeds, but job fails before reaching ECS deployment. This is blocking all production deployments.

Build Links:

Failing: https://app.circleci.com/pipelines/github/myorg/myapp/789/workflows/abc-123/jobs/1234
Last successful: https://app.circleci.com/pipelines/github/myorg/myapp/785/workflows/xyz-456/jobs/1230

Error:

[Errno 13] Permission denied: '/home/circleci/.aws/credentials'
Exited with code exit status 255

Occurs in "Configure AWS CLI" step of deploy-production job.

Timeline:

Last success: Jan 27, 6:45 PM EST (build #1230)
First failure: Jan 28, 8:30 AM EST (build #1234)
Frequency: 100% - all 12 builds since then failed
Changes: Updated circleci/aws-cli orb from 5.3.0 to 5.4.1 on Jan 28 at 8:00 AM EST
Impact: Production deployments blocked for 28 hours

Additional Resources

Best Practices When Opening a Support Ticket