search
HomeAboutContactNewsFAQ
githubEdit

AWS Debugging Guide

This is a quick-reference guide for governments troubleshooting a CiviForm deployment on AWS. It covers how to find logs, filter them for relevant events, and notify the CiviForm government support team.

hashtag
Finding Logs

CiviForms runs as a containerized service on Amazon ECS (Elastic Container Service). All container output is streamed to CloudWatch Logs and is also accessible directly from the ECS console.

hashtag
Navigating to the Logs Tab

  1. Sign in to the AWS Consolearrow-up-right and select the correct account and region (e.g., US East (N. Virginia)) from the top-right dropdown.

  2. Go to Amazon Elastic Container Service → Clusters.

  3. Click your CiviForms cluster (e.g., prod-civiform).

  4. Under the Services tab, click prod-civiform-service.

  5. Select the Logs tab.

You will see a paginated log stream from all running containers. The columns are:

  • Timestamp — when the log line was emitted (shown in UTC-5:00 by default)

  • Message — the raw log output

  • Task — the ECS task ID that generated the log

  • Container — which container within the task (e.g., prod-metrics-scraper, civiform)

circle-info

If you see the banner "Response size limits prevent displaying some newer logs," reduce your time range or toggle Continue fetching on.

hashtag
Filtering Logs in the ECS Console

Use the filter controls at the top of the Logs tab to narrow down what you see.

Filter by keyword

Type a word or phrase into the Filter logs search bar and press Enter. Useful patterns:

Goal
Search term

Application errors

ERROR

Warnings

WARN

Database issues

SQLException or db

Auth failures

401 or 403

Server errors

500

Filter by container

Use the Filter container dropdown to isolate logs from a specific container. For most debugging, select civiform (the main app container).

Filter by time range

Click Filter by a date and time range to scope logs to a specific incident window. This is especially useful when triaging a bug if you know when it occurred.

hashtag
Notifying the CiviForm team

To get support from the CiviForm team, notify the government support team by tagging @support in the #gov-support channel on the CiviForm Slack or emailing [email protected].

Include in your message:

  1. A screenshot or video of the error happening on CiviForm

  2. The log from AWS that you think is associated with the error

  3. Detailed instructions for how to re-create the error

hashtag
Example: Emails not sending from CiviForm on status updates

A program admin is reporting that they not receiving email updates CiviForm. They try logging in at 4pm on March 12th, 2026. You can search the logs during this time period, filter to "ERROR", and find the following logs:

You report this issue to the CiviForm support team and send along the logs and instructions for what they were doing that they expected to send an email (in this case, updating a status).

The CiviForm team responds that this is likely due to a configuration error where the the domain is not yet verified in SES. You need to follow the steps described in Email Configuration

PreviousTechnical Support

Last updated

Was this helpful?