- Docs
- Reference
- Step reference
- Step troubleshooting
Step troubleshooting
Find the message or the behaviour you see. Each entry says why it happens, what to check and how to fix it. Messages are quoted as they appear in the editor, the live log or the report.
In short
On this page you can
- Find the exact step message you see in the live log or the report.
- Learn why a step failed, errored or passed when it should not.
- Fix element, variable, API, database, mail, Kafka and Network problems.
- Fix AI, load-test, mobile and desktop step problems.
- Jump to the family page that explains the step in full.
How to use it
- Open the failed run: the live log of the Dry Run, or the report of the pipeline run.
- Read the failed step’s message and the reason after the colon.
- Search this page for the message, or open the section of the step type.
- Apply the fix, save the test case, and run a Dry Run again.
- If the message is not here, write to info@smartestqa.ai with the run link.
Element steps#
“Failed to click on "…": Element not found | Locator: …” (or Timeout, not clickable, stale)Element
- Why
- No locator of the action matched within the time, after 3 attempts and auto-heal. The reason after the colon tells which: “Element not found”, “Element not clickable” (something covers it), “Element not interactable” (hidden or disabled), “Timeout — element did not become ready in time”, “Element is no longer valid on the page (stale)”, “Frame not found”, “Invalid selector”, “Browser window/tab is not available”.
- Check
- The screenshot of the step: is the page the one you expect, or a login, error or loading page?
- The locator after
Locator:: does it still match the element in the app? - Did an earlier click open a new tab (Selenium stays on the old one)?
- Fix
- Fix or add a locator in Action Detail, preferring
idordata-testid. Add a wait for slow pages (Waits). For a new tab in Selenium, switch tabs in a Python step. Auto-heal does not run on login pages or when the app returns 401, 403 or 5xx.
Type added the text after the old valueElement
- Why
- Type does not clear the field; it appends.
- Fix
- Use a Clear & Type action for that field: replace the step’s action with one of type Clear & Type and enter the value again. Changing the type of the shared action itself changes every test case that uses it.
“Failed to select option from "…"”Element
The test went on after a failed Visibility CheckChecks
- Why
- A failed Visibility Check marks the step FAILED but does not stop the test case.
- Fix
- Where the flow must stop, read the value with Get and use an Assertion, which stops the case.
“Text or locator is required for visibility check.”Checks
- Fix
- Give the step an action with a locator, or an expected text value, or both.
Wait step: “no wait time given…”, “… is not a valid number of seconds”, “… is out of the allowed range (0.1 - 3600 s)”Wait
- Why
- The value of Wait (seconds) is empty, not a number, outside 0.1–3600, or a variable that could not be resolved.
- Fix
- Enter a number such as
2or0.5(dot as decimal mark). If it is a variable, make sure the step that sets it runs first.
Checks#
“No assertion type is selected for this step…” / “Unsupported assertion type: '…'”Assertion
- Fix
- Select the step and pick a type from the assertion type list in the right panel, for example Equals. See Assertion types.
“Expected is empty — enter the text to look for with '…'” / “'expected' value was not found…”Assertion
- Why
- Contains, Starts With and similar types need an expected value.
- Fix
- Fill expected, or switch to Is Empty / Is Not Empty if you only check presence.
“Actual is not a number: '…'” / “Expected is not a number: '…'”Assertion
- Why
- Greater Than and Less Than compare numbers. A value such as
€ 1.234,50or12 itemsis text. - Fix
- Add the To Number transform to the Get step that reads it. See Transforms.
An assertion fails although the values look the sameAssertion
- Why
- Text comparison is case-sensitive and does not trim spaces or line breaks.
- Fix
- Use Contains, or clean the value with Trim / Lower Case transforms. See Comparison rules.
Variables and code#
A step typed {{tc:name}} instead of the value, or the log says “… not found, treated as empty”Variables
- Why
- The reference could not be resolved: the name is spelled differently, the producing step did not run (inactive, skipped branch, failed), or it runs after this step.
- Check
- The exact output name of the producing step (case matters) and its position in the list.
- Fix
- Use the picker icon to insert the reference instead of typing it. See Reference syntax.
“Parameter key can only contain letters, digits and underscore”Variables
- Fix
- Rename the Get or Global parameter key:
order_id, notorder-idororder id.
“This key is already registered as a global parameter, please change the key value.: …” / “Names that produce a global parameter must be unique within the test case. Conflicts: …”Variables
- Fix
- Give each output a unique name within the test case, and do not reuse a name that another source already registered. See Steps that produce variables.
“Code body cannot be empty” / “… code is empty for Python step(s): … Dry Run was not started.”Code
- Why
- A Python or JavaScript step has no code, or in a web project the Python step has code only in the tab of the other engine (Selenium or Playwright).
- Fix
- Write the code in the tab of the engine the project uses, or remove the step. See Python or JavaScript.
The STATUS check failed (“… STATUS check failed … Returned value: …”)Code
- Why
- In Status mode the code produced a false value, or nothing.
- Fix
- Return
trueorfalseexplicitly. If the step should only act, set the output to N/A. See Output modes.
“The test could not start — a step's code or IF/ELSE/END structure is invalid…”Code
- Why
- An IF has no END, an ELSE has no IF, an IF or ELIF condition is empty, or a Python step does not compile. The run stops before the first step.
- Fix
- Check that every IF block ends with an END step and that each condition is a valid Python expression. See Conditions.
“[IF] Condition could not be evaluated”Code
- Why
- The condition raised an error, typically comparing text with a number.
- Fix
- Wrap numbers:
int({{tc:count}}) > 10; quote text:"{{tc:status}}" == "PAID".
“Project type could not be read - the code cannot be edited. Reload the page.”Code
- Fix
- Reload the page. The editor needs the project type to know the code format (web or mobile/desktop).
API#
The API step passed although the API returned 404 or 500API
- Why
- Any HTTP answer counts as a successful step; even a timeout lets the case continue.
- Fix
- Save
@statusinto a variable and add an Assertion. See Check the status code.
“Unsupported HTTP method: HEAD” (or OPTIONS) at run timeAPI
- Why
- The editor accepts HEAD and OPTIONS, but the runner sends only GET, POST, PUT, PATCH and DELETE.
- Fix
- Use GET instead, or call the endpoint from a Python step.
Send: “The request timed out (30s)…”, “Host not found…”, “Connection refused…”API
- Why
- Send runs from the SmartestQA server, which cannot reach internal or local addresses.
- Fix
- Add JSON paths by hand (plus icon) and test the step with a Dry Run on your agent. See Send.
“Fill in the key and the JSON path, or remove this row” / “JSON path is invalid and cannot work at runtime” / “No match in the response”API
- Fix
- Fill both the key and the path, or delete the row. Write paths like
data.items.0.idor$.data.items[0].id; use@statusand@header:Namefor status and headers. See Save values.
The API step ends as ERROR with an SSL or certificate errorAPI
- Why
- The API step always verifies certificates; self-signed and expired certificates are refused.
- Fix
- Use a valid certificate on the test environment, or an address with one.
Database, mail and Kafka#
“Asterisk (*) is not allowed…” / “Query must be in "SELECT ... FROM ..." format.” / “SQL query cannot be empty.”Database
- Fix
- Name the columns:
SELECT status, total FROM orders WHERE id = 1. See SQL rules.
“Configuration must be selected.” / “Output values cannot be empty.”Database
- Fix
- Pick the connection in Configuration and list one output name per column in Output Values. If the list is empty, create the connection on the Data Source page first.
“The column "…" was not found in the table…” / “The table "…" was not found.”Database
- Fix
- Names are case-sensitive in many databases. Quote uppercase or reserved names:
"User","user".
“Could not connect to the database…” / “Database authentication failed…”Database
- Why
- The database is not reachable from the machine that runs the test, or the credentials are wrong.
- Fix
- Test the connection on the Data Source page. For databases inside your network, run on your agent instead of the server.
The output variable of a Database step is empty or holds the wrong columnDatabase
- Why
- Outputs map to columns by position, not by name, and come from the first row. No row means no value.
- Fix
- List the outputs in the same order as the SELECT columns and check the query returns a row. See Output Values.
“Timeout: No email with OTP found within … seconds” (also “… with matching link …”, “No matching email …”)Mail
- Why
- No new, unread email matched the filters in time. Emails already read, or received more than 30 seconds before the step started, are ignored.
- Check
- The email reached the integration’s inbox (not spam, not another folder).
- Sender Filter and Subject Filter match the real email.
- The code matches OTP Pattern (Regex): a 4-digit code needs
\b(\d{4})\b.
- Fix
- Correct the filters or pattern, raise Timeout (seconds) (up to 600), and put the mail step right after the action that sends the email. See Which emails a step sees.
“Email integration has not been configured yet. Please configure email from the Integrations page first.”Mail
- Fix
- Ask an admin to add the test mailbox on the Integrations page, then open the mail dialog again.
“Failed to connect to mail server: …” / “Failed to connect to SMTP server: …” / “Failed to send email: …”Mail
- Fix
- Check the integration’s server, port and password (many providers need an app password), and that the machine running the test can reach the mail server.
“Kafka consume timed out after …s on topic '…': no matching message found …”Kafka
- Check
- The count of messages seen in the message. Zero means nothing arrived on the topic; a higher number means messages arrived but none matched.
- Fix
- Check the topic name, the Match Path (JSONPath) (for example
$.transferId) and the value; raise the timeout. See Consume.
“Kafka produce failed: delivery not confirmed within …s …”Kafka
- Fix
- The broker did not acknowledge in 10 seconds. Check bootstrap servers, security settings and credentials of the configuration, and that the broker is reachable from the machine running the test.
“No Kafka configuration found…”, “Topic may only contain letters, digits, dot, underscore and dash”, headers not a JSON objectKafka
- Fix
- Create the connection on the Data Source page (Kafka tab). Fix the topic name. Write headers as a JSON object:
{"h1":"v1"}.
Network#
“No matching request within …s”Network
- Why
- No completed call matched the URL, method and request type in scope. With Since previous step, only calls started by the step right before count.
- Check
- Run a List step at the same place and look at the calls in the report.
- Fix
- Correct the URL part, set Scope to “Whole session”, raise Wait up to (sec), or use Playwright if Selenium cannot see the call. To go on without it, set If no request to “Skip and continue”.
The Network step ends as WARNINGNetwork
- Why
- Failed calls (4xx, 5xx, network failures) or JS errors were seen, and On failed calls / JS errors is “Mark as warning”.
- Fix
- Read the errors in the report. Set the option to “Fail the step” to make them fail the test, or “Ignore”.
“URL is required”, “Invalid regular expression”, “Letters, digits and _ only”, “Name is used twice”Network
- Fix
- Enter part of the URL (or a prompt), fix the regex when Match is regex, and give each variable a unique simple name. See Save to variable.
AI steps#
The AI step button is disabled (“Enable '…' in Project Panel → AI Options”)AI
- Fix
- Ask an admin to switch on Enable AI and AI Document Analysis in the project’s AI options and to set up the AI provider. See Before you start.
“AI step FAILED (STOP_ON_ERROR): …”AI
- Why
- The AI answered false (AI Check), could not do the action (AI Do), or the AI service failed. AI steps from the dialog stop the case on failure.
- Fix
- Look at the screenshot in the report: was the page ready? Make the prompt more specific, or replace the step with a regular action and an Assertion.
“Please enter a prompt first.” / “Page Name is required” / “Output variable cannot be empty”AI
- Fix
- Fill the prompt and the page, and a variable name when Output Value is Value.
Load tests#
JMeter and k6 are greyed out: “This scenario has browser steps…”Load
- Fix
- Put the load test in a test case with API steps only. Generate creates that case for you.
“No API requests to test yet” / “Add API request steps to the test case first.”Load
“JMeter could not be found on this machine (…)” / “k6 could not be found on this machine (…)”Load
- Fix
- Install JMeter (and Java) on the machine that runs the test, or set
JMETER_HOME, then restart the agent. k6 is downloaded automatically unless downloads are turned off; otherwise install it or setK6_PATH.
“… of … requests failed (…%). Top error: …”Load
- Why
- At least one request failed; one is enough to fail the step.
- Fix
- Open the report’s requests and responses, fix the cause (expired token, wrong data, system overload), or lower the load.
“… exceeded the time limit …” / “… above the limit of … users …”Load
- Fix
- Reduce duration or users in the pipeline’s load settings. The limits are set by the platform administrator; contact info@smartestqa.ai to change them.
Mobile and desktop#
A mobile step can’t find its element (“… did not appear in time”)Mobile
- Why
- The screen differs from the recording, the element is off screen, or the locator matches nothing. Mobile steps are not auto-healed.
- Fix
- Add a Scroll or Wait For Visible step before it, and re-capture the element with a stable locator (accessibility id, resource-id). See Discover › Mobile.
A button under the on-screen keyboard can’t be tappedMobile
- Fix
- Add the Global action Hide Keyboard after typing, or Press Enter to submit. See Global actions.
“The text of "…" did not match the expected value "…" (found: "…")”Mobile
“The device screen is locked…” / “The application under test is not installed on the device.”Mobile
- Fix
- Unlock the device and keep the screen awake during runs; install the app (on Device Farm through the App Library) and run again.
No desktop agent is found, or the agent is offlineDesktop
- Fix
- Start the SmartTest agent on the machine with the app and check it is online. See Install the agent.
Typing into a password field does nothingDesktop
- Fix
- Use Type Key by Key; it types like a real keyboard. See Input and keys.
The step acts on the wrong windowDesktop
- Fix
- Add Switch Window with part of the target window’s title before the step. See App and window.
Still stuck#
Write to info@smartestqa.ai with the test case name, the run (Dry Run time or pipeline report link) and the step message.
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai