1. Docs
  2. Administration
  3. Integrations
  4. Troubleshooting

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.

17 min read Updated CustomersAdmins

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#

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.
“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.
“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.
The card says Ready although the integration is set upCatalogue
Why
The catalogue shows Active only when the integration is switched on. Datadog, Dynatrace and the CI cards always show Ready. See catalogue chip.
Fix
Open the page: if it says Disabled, turn the integration switch on.
“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.
“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 of this project’s company.
“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.
A saved token stops working after I changed the addressSetup
Why
Zephyr Scale, Azure DevOps, WhatsApp, APM and webhook headers never send a saved secret to a new server. See credentials.
Fix
Type the token again in the same save as the new address.

Jira#

“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.
“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.
“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.
A new task did not create a Jira issueJira
Check
  1. The page shows Active and Send Tasks to Jira 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: it sends every task, including the missed one. See What is sent.
The Jira status does not change when the task status changesJira
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 to a status reachable in one transition, or adjust the Jira workflow. See mapping.
“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 on, run Test Connection, then retry.
Get from Jira created tasks for stories and epicsJira
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 off, or connect a Jira project used only for test findings.

Azure DevOps#

“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.
“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.
“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.
“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.
A new task has no work item yetAzure 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, or turn on Automatic Synchronization.
“No test case results in this run” or no run in Test PlansAzure DevOps
Check
  1. Publish runs 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#

“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.
“This feature is disabled in settings”Xray
Fix
Open Settings and turn on Test Case → Xray or Xray → Test Case in Sync Settings.
No Test Execution appears in Xray after a runXray
Why
In this version, executions are exported on request, not after every pipeline. See results.
Fix
Ask an AI assistant connected through MCP to export the run to Xray. Only mapped test cases are included: run Send to Xray first. “No Xray mappings found for tests in this log” means none of the run’s test cases is mapped.
Pull from Xray did not bring all my testsXray
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.
“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#

“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).
“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.
“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.
“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.
“Requirements were not imported: Zephyr Cloud needs the Jira integration of this project to read issues.”Zephyr
Fix
Set up Jira in the same project, then click Get from Zephyr again.
“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.
“The integration is turned off”Zephyr
Fix
Turn Integration active on in Connection Status.

Confluence#

“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.
“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.
“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.
“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.
“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.
“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 and send again.
“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#

“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 on the page.
“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.
No message arrives after a pipelineChat
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.
  3. Send Test Message 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.
“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.
The daily summary did not arriveChat
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 before the first run of the day. See daily summary.
“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 +.
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://”.
WhatsApp: the test works but run messages never arriveWhatsApp
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.
“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#

“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.
“At most 10 custom headers” / “Invalid header name: …”Webhook
Fix
Keep 10 headers or fewer, named with letters, digits and - only.
“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 again. Open Deliveries for status codes of real events.
My receiver rejects the signatureWebhook
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 invalidates the old one at once.
Fix
Follow Verify the signature.
“A project can have at most 20 webhooks.”Webhook
Fix
Delete unused webhooks, or send to one endpoint that fans out.
“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#

“SmartestQA: trigger failed (HTTP …)”CI/CD
Why
SmartestQA refused to start the pipeline. 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, and the agent was not deleted.
  2. The key’s user may open the project: Admins 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.
“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).
“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) and copy the step again, or speed the pipeline up. See exit code.
“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.
The build fails with state DISCONNECTEDCI/CD
Why
A test case stayed running for more than 2 hours: the agent that ran it went offline.
Fix
Check that the agent is online (when is an agent Online) and run again.
“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.
“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.
“This project has no pipelines yet.” / “Couldn't load the pipelines.”CI/CD
Fix
Create a pipeline in Schedule (Go to Pipelines), or refresh the page.

Datadog and Dynatrace#

“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”.
“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.
“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.
“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.
“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://.
“Rate limited (429): try again in a minute”APM
Fix
Wait a minute. Fewer watched metrics (at most 20) mean fewer calls per report.
“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 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.
“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#

“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. See Before you start.
“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 need it.
“Mail integration with this name already exists”Email
Fix
Choose another Integration Name; names are unique per project.
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 for internal servers).
Fix
Adjust the filter or the step timeout in Automate, and keep the test mailbox free of manual reading.

Not listed here? Write to info@smartestqa.ai with the integration, the exact message and the time it happened.

Didn’t find your answer?Write to support with your project name and what you see on screen.

info@smartestqa.ai
© 2026 Selenity Technology · SmartestQAsmartestqa.aiThis page as MarkdownChecked against smarttest-fe predev 2a8c79cc (en.json, pages/integrations), smarttest-be 633c2a03 (integration controllers and clients, ci/smartest-ci.sh)