---
title: "Troubleshooting"
section: "Integrations"
description: "Fixes for SmartestQA integrations: connection and token errors for Jira, Azure DevOps, Xray, Zephyr, Confluence, Slack, Teams, WhatsApp, webhooks, CI/CD, APM and email."
url: https://docs.smartestqa.ai/en/integrations-troubleshooting.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "integration error authentication failed access denied token rejected not found webhook url required test failed no notification daily summary trigger failed timeout signature imap smtp apm no data"
---
# Integrations: Troubleshooting integrations

Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it. Messages are quoted as SmartestQA shows them.

## In short

**On this page you can**

- Fix connection tests that fail with an authentication, permission or address error.
- Find out why a ticket, message or report did not arrive after a run.
- Repair CI steps that cannot start a pipeline or time out.
- Fix webhook signature checks and APM charts without data.
- Fix mailboxes that refuse IMAP or SMTP.

**How to use it**

1. Copy the exact message from the page, the dialog or the CI log.
2. Search this page for it, or open the section of the integration.
3. Run the checks in order; most problems are the token, its scope or the address.
4. Apply the fix, then click Test Connection again.
5. Still stuck: write to info@smartestqa.ai with the message and the time.

## All integrations

### Problem: I don’t see Integrations in the menu, or “Please contact your administrator to access this feature.” _(Access)_

- **Why:** Integrations are for company Admins only.
- **Fix:** Ask an Admin to set it up, or to make you an Admin. See [roles](https://docs.smartestqa.ai/en/company-settings-roles.html).

### Problem: “Please select a project to configure the … integration.” _(Access)_

- **Why:** Integrations belong to a project and none is selected.
- **Fix:** Select the project in the top bar. The page reloads for that project.

### Problem: “Couldn't load integration status.” _(Catalogue)_

- **Why:** The status call failed, usually a network blip or an expired session. All cards then show Ready.
- **Fix:** Click **Retry**. If it keeps failing, log in again.

### Problem: The card says Ready although the integration is set up _(Catalogue)_

- **Why:** The catalogue shows Active only when the integration is switched on. Datadog, Dynatrace and the CI cards always show Ready. See [catalogue chip](https://docs.smartestqa.ai/en/integrations-numbers.html#hub-status).
- **Fix:** Open the page: if it says **Disabled**, turn the integration switch on.

### Problem: “Please test the connection before proceeding” _(Setup)_

- **Why:** The Jira, Xray and Confluence wizards only continue after a successful **Test Connection** in the first step.
- **Fix:** Fill the address, user and token, click **Test Connection**, wait for the green chip, then **Next**. If the test fails, see the entry for that integration below.

### Problem: “Error saving settings: …” / “Settings could not be saved.” _(Setup)_

- **Why:** The server refused the settings. The text after the colon says why: a missing field, an address rule, or a token that must be re-entered.
- **Fix:** Correct the field named in the message and save again. If the message is “Project access denied”, you are not an [Admin](https://docs.smartestqa.ai/en/company-settings-roles.html) of this project’s company.

### Problem: “Error updating setting” _(Setup)_

- **Why:** A switch saves at once and the save failed. The switch goes back to its old position.
- **Fix:** Click **Refresh** and try again. If it repeats, log in again.

### Problem: A saved token stops working after I changed the address _(Setup)_

- **Why:** Zephyr Scale, Azure DevOps, WhatsApp, APM and webhook headers never send a saved secret to a new server. See [credentials](https://docs.smartestqa.ai/en/integrations.html#secrets).
- **Fix:** Type the token again in the same save as the new address.

## Jira

### Problem: “Authentication failed: …” or the chip “Connection Error” _(Jira)_

- **Why:** Jira refused the user and token at `/rest/api/2/myself`.
- **Check:** 1. The **Authentication Type** matches your Jira: **API Token (Jira Cloud)** for Cloud, **Personal Access Token (Server/DC)** for Server and Data Center.
  2. For Cloud, **Username / Email** is the Atlassian email, not a display name.
  3. The token was copied whole and has not expired or been revoked.
  4. The **Jira URL** is the site root, for example `https://your-company.atlassian.net`, without `/jira` or a project path.
- **Fix:** Create a new token, paste it in **API Token** and test again. See [Before you start](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-before).

### Problem: “Connection error: …” _(Jira)_

- **Why:** SmartestQA could not reach the Jira address: wrong host, Jira behind a firewall, or a certificate problem.
- **Fix:** Check the address in a browser. An on-premises Jira must be reachable from the SmartestQA servers; ask IT to allow it.

### Problem: “Error loading Jira metadata” / “Please select a Jira project first.” _(Jira)_

- **Why:** The issue types, priorities or statuses of the chosen project could not be read, or no project is chosen in step 2.
- **Fix:** Pick the **Jira Project** again. Check that the Jira user can browse that project.

### Problem: A new task did not create a Jira issue _(Jira)_

- **Check:** 1. The page shows **Active** and [**Send Tasks to Jira**](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-setup) is on (shown under **Sync Direction**).
  2. **Test Connection** gives OK.
  3. The default issue type exists in the Jira project and has no extra required fields.
- **Fix:** Correct the setting, then click [**Send to Jira**](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-sent): it sends every task, including the missed one. See [What is sent](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-sent).

### Problem: The Jira status does not change when the task status changes _(Jira)_

- **Why:** The status is changed through a Jira transition whose name matches the mapped status. If the workflow has no such transition from the current status, nothing changes.
- **Fix:** Map the [task status](https://docs.smartestqa.ai/en/tasks-statuses.html) to a status reachable in one transition, or adjust the Jira workflow. See [mapping](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-mapping).

### Problem: “Error starting synchronization” / “Error starting synchronization from Jira” _(Jira)_

- **Why:** The sync request failed, often because the integration is switched off (“Jira sync is disabled for this project”) or the token expired.
- **Fix:** Turn [**Integration Active**](https://docs.smartestqa.ai/en/integrations.html#concepts) on, run **Test Connection**, then retry.

### Problem: Get from Jira created tasks for stories and epics _(Jira)_

- **Why:** The incoming sync turns the 200 newest unlinked issues of the project into tasks, whatever their type.
- **Fix:** Delete the unwanted tasks, turn [**Get Updates from Jira**](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-setup) off, or connect a Jira project used only for test findings.

## Azure DevOps

### Problem: “Authentication failed: check the personal access token” / “Access denied: the token lacks the required scope” _(Azure DevOps)_

- **Why:** The token is wrong, expired, or lacks a scope. A sign-in page answer is reported as “Authentication failed: check the personal access token and its scopes”.
- **Fix:** Create a token with Work Items (read & write), Test Management (read & write) and Project and Team (read) for the right organization, and paste it. See [Before you start](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#ado-before).

### Problem: “Not found: check the organization/collection URL and project name” / “Cannot reach Azure DevOps (…)” _(Azure DevOps)_

- **Fix:** Use `https://dev.azure.com/org` for Services and the collection URL for Server, and pick the project from the list after a successful test. A Server instance must be reachable from SmartestQA.

### Problem: “Organization / collection URL and project are required.” / “Personal access token is required.” _(Azure DevOps)_

- **Fix:** Fill both fields; the token is required on the first save.

### Problem: “The server address changed: re-enter the personal access token” _(Azure DevOps)_

- **Why:** The saved token is never sent to a new address.
- **Fix:** Paste the token again and save.

### Problem: A new task has no work item yet _(Azure DevOps)_

- **Why:** Work items are created by the timed sync or the button, not when the task is saved.
- **Fix:** Click [**Send tasks to Azure DevOps**](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#ado-sent), or turn on **Automatic Synchronization**.

### Problem: “No test case results in this run” or no run in Test Plans _(Azure DevOps)_

- **Check:** 1. [**Publish runs**](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#ado-test-plans) is on.
  2. The token has Test Management (read & write).
  3. The run had test case results; a run stopped before any test case finished has none.
- **Fix:** Fix the cause and click **Retry** on the run row.

## Xray

### Problem: “Authentication failed: …” / “Authentication failed - no token received” _(Xray)_

- **Why:** Xray Cloud refused the Client ID and Client Secret.
- **Fix:** Create a new API key in Xray Global Settings › API Keys and paste both values. Keep **Xray Cloud URL** at `https://xray.cloud.getxray.app`. Xray Server and Data Center are not supported.

### Problem: “This feature is disabled in settings” _(Xray)_

- **Fix:** Open **Settings** and turn on **Test Case → Xray** or **Xray → Test Case** in **Sync Settings**.

### Problem: No Test Execution appears in Xray after a run _(Xray)_

- **Why:** In this version, executions are exported on request, not after every [pipeline](https://docs.smartestqa.ai/en/schedule-create.html). See [results](https://docs.smartestqa.ai/en/integrations-test-management.html#xray-results).
- **Fix:** Ask an AI assistant connected through [MCP](https://docs.smartestqa.ai/en/mcp.html) to export the run to Xray. Only mapped test cases are included: run [**Send to Xray**](https://docs.smartestqa.ai/en/integrations-test-management.html#xray-sync) first. “No Xray mappings found for tests in this log” means none of the run’s test cases is mapped.

### Problem: Pull from Xray did not bring all my tests _(Xray)_

- **Why:** One pull reads up to 100 Tests, and skips Tests that SmartestQA created.
- **Fix:** Keep the Xray project focused on the tests you automate, or ask support about larger imports.

### Problem: “Mapping could not be deleted” / “Settings could not be deleted” _(Xray)_

- **Fix:** Refresh the page and try again; the item may already be gone.

## Zephyr Scale

### Problem: “The API token was rejected” / “The token has no access to this project” _(Zephyr)_

- **Why:** 401 or 403 from Zephyr or Jira.
- **Fix:** Cloud: create a new Zephyr API access token in your Zephyr profile. Data Center: a Jira personal access token of a user who can read the project (and write, for results).

### Problem: “Not found (check the address and the project key)” / “Could not reach Zephyr: …” _(Zephyr)_

- **Check:** 1. The **Jira project key**, for example `PAY`.
  2. Cloud: the **Zephyr region** matches your site (EU sites use the EU region).
  3. Data Center: the **Jira address** starts with `https://` and is reachable from SmartestQA.

### Problem: “The Jira project key (and, for Data Center, the Jira address) are required.” / “The API token is required.” _(Zephyr)_

- **Fix:** Fill the fields named. The token is required on the first save.

### Problem: “The server changed: re-enter the API token” / “The address must start with https://” _(Zephyr)_

- **Fix:** Enter the full address with `https://` and paste the token again in the same save.

### Problem: “Requirements were not imported: Zephyr Cloud needs the Jira integration of this project to read issues.” _(Zephyr)_

- **Fix:** Set up [Jira](https://docs.smartestqa.ai/en/integrations-issue-trackers.html#jira-setup) in the same project, then click [**Get from Zephyr**](https://docs.smartestqa.ai/en/integrations-test-management.html#zephyr-sync) again.

### Problem: “No test case in this run is linked to Zephyr” _(Zephyr)_

- **Why:** Results are written only for scenarios that came from Zephyr or were sent there.
- **Fix:** Run [**Get from Zephyr**](https://docs.smartestqa.ai/en/integrations-test-management.html#zephyr-sync) or [**Send to Zephyr**](https://docs.smartestqa.ai/en/integrations-test-management.html#zephyr-sync), then run the [pipeline](https://docs.smartestqa.ai/en/schedule-create.html) again.

### Problem: “Another sync is still running” _(Zephyr)_

- **Fix:** Wait for the current import or export; the page updates when it ends. A job stuck for 45 minutes stops blocking new ones.

### Problem: “The integration is turned off” _(Zephyr)_

- **Fix:** Turn **Integration active** on in **Connection Status**.

## Confluence

### Problem: “Kimlik dogrulama hatasi. Email ve API token kontrol edin.” / “Connection Error” _(Confluence)_

- **Why:** Confluence answered 401: email or API token wrong. In this version the Confluence test messages appear in Turkish; this one means “Authentication error. Check the email and API token.”
- **Fix:** Use the Atlassian account email and a new API token. The **Confluence URL** is the site root, for example `https://your-site.atlassian.net`.

### Problem: “Baglanti hatasi: …” / “Hata: …” _(Confluence)_

- **Why:** Connection error (shown in Turkish): the address is wrong or not reachable, or not a Confluence Cloud site.
- **Fix:** Open the address in a browser and copy the site root. “Confluence URL is not configured” means the field is empty.

### Problem: “Space not found: …” _(Confluence)_

- **Fix:** Use the space key (for example `QA`), not the space name, and check that the account can see the space.

### Problem: “Could not send report. Check reportsParentPageId setting.” / “Sayfa olusturulamadi” _(Confluence)_

- **Why:** The report page could not be created (“Sayfa olusturulamadi” means “Page could not be created”): the parent page ID is missing, wrong, in another space, or the account may not add pages there.
- **Fix:** Copy the number from the parent page’s URL into **Reports Parent Page** on the **Synchronization** tab. See [parent page IDs](https://docs.smartestqa.ai/en/integrations-confluence.html#before).

### Problem: “Reports sync disabled” / “Documentation sync disabled” / “Confluence not configured” _(Confluence)_

- **Fix:** Turn on the card’s switch on the **Synchronization** tab, and **Enable Integration** in the settings.

### Problem: “No new reports to send (total: …)” _(Confluence)_

- **Why:** Every finished run already has a page under this parent, or the remaining runs are still running.
- **Fix:** Nothing to do. Run a [pipeline](https://docs.smartestqa.ai/en/schedule-create.html) and send again.

### Problem: “Zaten bir senkronizasyon devam ediyor: …” _(Confluence)_

- **Why:** “A sync is already running”: another send is in progress for this project.
- **Fix:** Wait until it ends. A lock older than 60 minutes is released.

## Slack, Teams and WhatsApp

### Problem: “Webhook URL required” / “No webhook URL configured for this project” _(Chat)_

- **Fix:** Paste the webhook URL in the settings dialog. After saving, the field is empty on purpose (“Existing webhook set. Enter a new URL to change it.”); to test it, use [**Send Test Message**](https://docs.smartestqa.ai/en/integrations-notifications.html#slack) on the page.

### Problem: “Failed to send test message” / “Test failed” _(Chat)_

- **Check:** 1. Slack: the URL starts with `https://hooks.slack.com/services/` and the app is still installed in the workspace.
  2. Teams: the URL is a Workflows webhook and the workflow is on.
  3. The webhook was not deleted or regenerated on the other side.
- **Fix:** Create a new webhook, paste it in **Settings**, save and send a test.

### Problem: No message arrives after a pipeline _(Chat)_

- **Check:** 1. The page shows **Active** (not Disabled).
  2. The right switch is on: a run where every test passed sends **Pipeline Completed**; a run with any failed or unrun test sends **Pipeline Failed**. See [events](https://docs.smartestqa.ai/en/integrations-notifications.html#events).
  3. [**Send Test Message**](https://docs.smartestqa.ai/en/integrations-notifications.html#slack) works.
  4. You did not rely on **Test Failed**: this version sends no per-test message.
  5. WhatsApp: **Finished runs: only when a test failed** skips green runs.
- **Fix:** Turn on the event you expected, or the other of Completed and Failed.

### Problem: “This is an old Office 365 connector URL. Microsoft retired connectors in May 2026, so messages may no longer arrive.” _(Teams)_

- **Fix:** Create a Workflows webhook with the template “Send webhook alerts to a channel” and paste its URL instead. See [Teams](https://docs.smartestqa.ai/en/integrations-notifications.html#teams).

### Problem: The daily summary did not arrive _(Chat)_

- **Why:** The summary is skipped on a day when the channel already sent another message before the summary hour. The hour is compared with the server’s clock.
- **Fix:** Move [**Summary Time**](https://docs.smartestqa.ai/en/integrations-notifications.html#daily-summary) before the first run of the day. See [daily summary](https://docs.smartestqa.ai/en/integrations-numbers.html#daily-summary).

### Problem: “Phone number ID must be the numeric ID from WhatsApp Manager, not the phone number” _(WhatsApp)_

- **Fix:** Copy the ID from WhatsApp Manager › Phone numbers. It is a long number without `+`.

### Problem: WhatsApp: “Invalid phone number(s)…”, “At least one recipient is required”, “SmartestQA address is required for report links” _(WhatsApp)_

- **Fix:** Write numbers in international format, for example `+905321234567`, one per line, up to 20. Enter the SmartestQA address starting with `http://` or `https://`. Other format rules: “Template language looks like tr, en or en_US”, “API version looks like v23.0”, “Template names use lowercase letters, digits and _”, “API base URL must start with https://”.

### Problem: WhatsApp: the test works but run messages never arrive _(WhatsApp)_

- **Why:** The test uses Meta’s `hello_world` template. Run messages use the SmartestQA templates, which must exist and be approved in your WhatsApp Manager in the **Template language**.
- **Fix:** Create the four templates exactly as listed on the WhatsApp page, wait for approval, and check **Last delivery error**. See [templates](https://docs.smartestqa.ai/en/integrations-notifications.html#whatsapp-before).

### Problem: “Re-enter the access token when changing the API base URL” / “Phone number ID and access token are required” _(WhatsApp)_

- **Fix:** Paste the token in the same save as the new API address; both ID and token must be set before a test.

## Webhooks

### Problem: “URL must be a valid http(s) address” / “Name is required” / “Select at least one event” _(Webhook)_

- **Fix:** Use a full `http://` or `https://` address up to 2,000 characters; link-local and cloud metadata addresses are refused. Give a name and tick at least one event.

### Problem: “At most 10 custom headers” / “Invalid header name: …” _(Webhook)_

- **Fix:** Keep 10 headers or fewer, named with letters, digits and `-` only.

### Problem: “Test failed: …” _(Webhook)_

- **Check:** 1. “HTTP 401/403”: your endpoint wants an auth header; add it under **Custom headers (optional)**.
  2. “HTTP 404”: the path is wrong.
  3. A timeout or connection error: the endpoint did not answer within 10 seconds, or SmartestQA cannot reach it.
- **Fix:** Fix the endpoint and click [**Send test**](https://docs.smartestqa.ai/en/integrations-webhooks.html#retries) again. Open **Deliveries** for status codes of real events.

### Problem: My receiver rejects the signature _(Webhook)_

- **Check:** 1. You compute the HMAC over the raw body bytes, not over re-serialised JSON.
  2. You compare with the whole header, including `sha256=`, in lowercase hex.
  3. You use the current secret; [**Regenerate secret**](https://docs.smartestqa.ai/en/integrations-webhooks.html#manage) invalidates the old one at once.
- **Fix:** Follow [Verify the signature](https://docs.smartestqa.ai/en/integrations-webhooks.html#verify-signature).

### Problem: “A project can have at most 20 webhooks.” _(Webhook)_

- **Fix:** Delete unused webhooks, or send to one endpoint that fans out.

### Problem: “Could not load webhooks.” / “Could not save the webhook.” _(Webhook)_

- **Fix:** Refresh the page. If saving keeps failing, read the error under the field; it names the rule.

## CI/CD

### Problem: “SmartestQA: trigger failed (HTTP …)” _(CI/CD)_

- **Why:** SmartestQA refused to start the [pipeline](https://docs.smartestqa.ai/en/schedule-create.html). The response body above the line says why, for example `ERR_PROJECT_ACCESS_DENIED` or `ERR_INVALID_API_KEY`.
- **Check:** 1. The secret holds an agent API key, copied with [**Copy API Key**](https://docs.smartestqa.ai/en/agent-pool-agents.html#api-key), and the agent was not deleted.
  2. The key’s user may open the project: [Admins](https://docs.smartestqa.ai/en/company-settings-roles.html) see their company’s projects, Users only projects they were given.
  3. `PIPELINE_ID` belongs to this project.
- **Fix:** Update the CI secret, or give the key’s user access to the project. See [Before you start](https://docs.smartestqa.ai/en/integrations-cicd.html#before).

### Problem: “SMARTEST_URL is not set” / “SMARTEST_API_KEY is not set” / “PIPELINE_ID must be a number” _(CI/CD)_

- **Fix:** Check the variables in the CI file and that the secret is exposed to this job (protected branches, forks and pull requests from forks often get no secrets).

### Problem: “SmartestQA: timed out after … min; the run continues in SmartestQA.” _(CI/CD)_

- **Why:** The run took longer than `SMARTEST_TIMEOUT_MIN`. The step exits with 2; the run goes on.
- **Fix:** Raise [**Timeout (min)**](https://docs.smartestqa.ai/en/integrations-cicd.html#settings) and copy the step again, or speed the [pipeline](https://docs.smartestqa.ai/en/schedule-create.html) up. See [exit code](https://docs.smartestqa.ai/en/integrations-numbers.html#ci-exit).

### Problem: “status check failed (HTTP …), retry n/5” / “status endpoint unreachable” / “status check refused (HTTP 401)” _(CI/CD)_

- **Why:** The CI runner lost the connection to SmartestQA, or the key no longer has access. After 5 failed checks in a row the step stops with 2.
- **Fix:** Check the runner’s network and proxy to `SMARTEST_URL`, and the key.

### Problem: The build fails with state DISCONNECTED _(CI/CD)_

- **Why:** A test case stayed running for more than 2 hours: [the agent](https://docs.smartestqa.ai/en/agent-pool-agents.html) that ran it went offline.
- **Fix:** Check that the agent is online ([when is an agent Online](https://docs.smartestqa.ai/en/quick-start-connect.html#agent-online-rule)) and run again.

### Problem: “could not fetch the JUnit report (HTTP …)” _(CI/CD)_

- **Fix:** The result and exit code are still valid. Re-run the job; if it repeats, report the time and run id to info@smartestqa.ai.

### Problem: “Enter a JSON object, for example {"ENV":"uat"}.” _(CI/CD)_

- **Fix:** Use double quotes and braces: `{"ENV":"uat","USER":"qa1"}`. Arrays and plain text are refused.

### Problem: “This project has no pipelines yet.” / “Couldn't load the pipelines.” _(CI/CD)_

- **Fix:** Create a pipeline in **Schedule** ([**Go to Pipelines**](https://docs.smartestqa.ai/en/schedule-timing.html#scheduled-runs)), or refresh the page.

## Datadog and Dynatrace

### Problem: “Authentication failed (401): check the API key” / “Datadog API key is not valid for this site” _(APM)_

- **Fix:** Check the key and the **Datadog site**: a key from `datadoghq.eu` is not valid on `datadoghq.com`. Dynatrace: “check the API token”.

### Problem: “Permission denied (403): …” _(APM)_

- **Fix:** Datadog: give the Application key the `timeseries_query` permission. Dynatrace: give the token `metrics.read`, and `events.ingest` to send events.

### Problem: “API key is valid but the Application key is missing; it is required to read metrics” _(APM)_

- **Fix:** Create an Application key in Datadog and paste it in **Application key**.

### Problem: “Not found (404): check the Datadog site / environment URL” / “Cannot reach …” _(APM)_

- **Fix:** Use the site value (for example `datadoghq.eu`) or the full Dynatrace environment URL, and check that SmartestQA can reach a Managed instance.

### Problem: “Datadog / Dynatrace SaaS addresses must use https” / “Only http/https URLs are allowed” / “Dynatrace environment URL is required” _(APM)_

- **Fix:** Enter the address with `https://`. Only on-premises Dynatrace Managed may use `http://`.

### Problem: “Rate limited (429): try again in a minute” _(APM)_

- **Fix:** Wait a minute. Fewer watched metrics (at most 20) mean fewer calls per report.

### Problem: “The APM returned no data for this run window. Check the metric filters (service / host).” _(APM)_

- **Check:** 1. The service or host name in the query matches your APM exactly.
  2. [**Preview last hour**](https://docs.smartestqa.ai/en/integrations-apm.html#set-up) shows data.
  3. Datadog `trace.*` metrics need the Datadog Agent with APM.
  4. The servers under test send metrics to this APM account.
- **Fix:** Edit the queries and reopen the report; saving the connection clears the saved series.

### Problem: “Datadog query error: …” / “Could not read server metrics” _(APM)_

- **Fix:** Test the query in Datadog’s metric explorer, then paste it in the metric’s **Query**.

## Email

### Problem: “IMAP connection failed: …” _(Email)_

- **Check:** 1. You used an app password, not the normal password. Gmail needs two-step verification first.
  2. IMAP is enabled for the mailbox (corporate accounts: ask IT).
  3. Server and port: usually 993 with SSL.
  4. The **Default Folder** exists (`INBOX`).
- **Fix:** Correct the field and click [**Save & Test**](https://docs.smartestqa.ai/en/integrations-email.html#set-up). See [Before you start](https://docs.smartestqa.ai/en/integrations-email.html#before).

### Problem: “SMTP connection failed: …” / “Some connections failed” _(Email)_

- **Fix:** Use port 587 with TLS or 465 with SSL, and check that the account may send mail. Reading still works when only SMTP fails; only Send [Mail steps](https://docs.smartestqa.ai/en/automate-steps-mail.html) need it.

### Problem: “Mail integration with this name already exists” _(Email)_

- **Fix:** Choose another **Integration Name**; names are unique per project.

### Problem: A mail step finds no email (“No matching email found…”, “Timeout waiting for email…”) _(Email)_

- **Check:** 1. The email arrived in the folder the step reads, not in spam.
  2. It is unread and arrived at most 30 seconds before the step started.
  3. The subject or sender filter matches.
  4. The test runs where the mail server is reachable ([an agent](https://docs.smartestqa.ai/en/agent-pool-agents.html) for internal servers).
- **Fix:** Adjust the filter or the step timeout in **[Automate](https://docs.smartestqa.ai/en/automate.html)**, and keep the test mailbox free of manual reading.

Not listed here? Write to [info@smartestqa.ai](mailto:info@smartestqa.ai) with the integration, the exact message and the time it happened.
