1. Docs
  2. Build tests
  3. Analyze
  4. Troubleshooting

Troubleshooting

Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it.

15 min read Updated CustomersAdmins

In short

On this page you can

  • Fix AI wizard errors, from a greyed-out button to failed scenarios.
  • Solve save, date and validation messages on requirements.
  • Sort out test case links, Automate on a sub and pipeline sync.
  • Understand assessment errors and skipped sub-requirements.
  • Resolve folder, module, archive and document problems.

How to use it

  1. Copy the exact message or describe the symptom.
  2. Find it under the matching heading (use the page search).
  3. Check the points under Check in order.
  4. Apply the Fix; if it persists, write to info@smartestqa.ai with the message and the requirement ID.

AI wizard: Import and outline#

Analyze with AI is greyed out, or “AI is disabled for project n”AI
Why
The button needs files attached and two project options: Enable AI and AI Document Analysis. Its tooltip names the missing one, for example “Enable 'AI Document Analysis' in Project Panel → AI Options”.
Check
  1. At least one file is attached (“n file(s) attached”).
  2. You are not in the Documents folder.
Fix
Ask an Admin to switch the options on in Project Panel › AI Options (Users cannot open Project Panel; see Roles). Then reload Analyze. See Before you start.
“AI API key is not configured (provider=…). Set it in Admin Panel (Smartest AI) or Project Preferences (Own Account).”AI
Why
AI is on, but the project’s AI account has no key.
Fix
An Admin enters the key for your own AI account in Project Panel › AI Options, or switches the project to SmartestQA’s AI account. If you use SmartestQA’s account and still see this, write to info@smartestqa.ai.
“Selected model/provider does not support image analysis (vision).”AI
Why
You attached screenshots, and the project’s AI model cannot read images.
Fix
Remove the images and attach the document text, or ask an Admin to choose a model that reads images in AI Options.
“name could not be read and was left out of the analysis” / “Could not read file content”Import
Why
The browser could not read the file, or its type cannot be turned into text. The analysis continues without it.
Check
  1. The file opens on your computer and is not password-protected.
  2. Its type is in the accepted list.
  3. Spreadsheets (.xlsx, .xls) may not convert well; save the sheet as .csv instead.
Fix
Re-save the file as .docx, .pdf (with text), .txt or .md and attach it again. For a picture of a document, attach it as a screenshot.
“PDF does not contain extractable text. It may be a scanned/image PDF.”Import
Why
The PDF holds pictures of pages, not text.
Fix
Export the original as a text PDF or .docx, or attach the pages as images (PNG or JPG).
“n file(s) were already attached and were skipped”Import
Why
A file with the same name, size and date is already in the list. Nothing is wrong.
Fix
None needed. To replace a file, remove it from the list first.
“Please select a file first” / “Please select a folder first”Import
Fix
Select a requirement folder in the tree, attach a file, then click Create as Document or Analyze with AI again.
“No requirements could be derived. Check the document has readable content, or add a screenshot.”Outline
Why
The AI answered, but found nothing it could turn into requirements.
Check
  1. The document has real content, not only headings or a table of contents.
  2. It is not a scanned PDF (see above).
  3. Additional Instructions for AI does not exclude everything.
Fix
Attach the chapter that describes behaviour, add a screenshot of the screen, or write the flow in a .txt file in plain sentences. Then click Analyze with AI again.
“Analysis failed” / dialog “Document Analysis” with “Outline generation failed: …”Outline
Why
The outline request failed. Common reasons: the AI provider returned an error or a quota limit, no readable content reached the server (“No readable document or image content was provided.”, “At least one document or image is required”), or the browser stopped waiting after 3 minutes.
Check
  1. The text after “Outline generation failed:” names the cause.
  2. The document is not very long; a whole manual can exceed what the model handles in time.
Fix
Retry from the dialog. For long documents, split them by chapter or module and run one folder at a time with a Target scope. For provider errors, see AI key or ask your Admin about the AI account’s quota.
“No application metadata yet — no page map, no notes. Scenarios will be generated from the document alone.”Outline
Why
The project has no App Map pages and no active Notes, so the AI knows only the document.
Fix
Generation still works, but steps will rarely match your controls. Map the pages first: Discover Your App, Update map and Notes.

AI wizard: steps, coverage and Create#

Scenarios show failed: “No steps were produced for this scenario.” / “n scenario(s) generated, m failed — you can retry the failed ones”Steps
Why
Step generation runs in batches with a time budget of 420 seconds on the server, and at most 3 generations run at once. A batch that times out, or waits too long for a free slot, leaves its scenarios without steps.
Fix
Keep the failed scenarios selected and click Generate steps again; finished ones are skipped. Select fewer scenarios per run if it keeps failing.
“Every selected scenario already has steps.”Steps
Fix
Nothing to do. Click Continue to review, or select scenarios that still show outline.
Continue to review (0) is greyed outSteps
Why
None of the selected scenarios has steps yet. See Wizard counts.
Fix
Click Generate steps first.
Many steps show ✗ and coverage is redCoverage
Why
A ✗ step found no matching action in your project. See Scenario coverage.
Fix
Record the missing controls with Record Actions (web), then click Check Coverage. Next time, set a Target scope so the AI uses the right pages’ actions.
“Please select a Start Page URL.” / “No URLs available. Please add one.” / “Real URL could not be resolved.” / “Failed to fetch start page URLs.”Coverage
Why
Record Actions needs a Start Page URL with an address for the chosen environment.
Fix
Add one with Manage URLs or in Start Page URLs, pick an environment that has an address, and try again. If the browser extension is missing, see extension not detected.
“Coverage check failed.”Coverage
Fix
Reload the page (save a draft first) and click Check Coverage again. If it keeps failing, write to info@smartestqa.ai.
The note says scenarios with ≥70% coverage are selected automatically, but all are selectedCreate
Why
In this version every scenario starts selected, whatever its coverage.
Fix
Untick the scenarios you do not want to create before clicking Create.
“n selected scenario(s) have no steps yet. Press “Generate steps” first, or uncheck them…” / “Please select at least one requirement.”Create
Why
Create would make empty test cases, or nothing is selected.
Fix
Go Back to scenarios, generate steps for those scenarios or untick them, and select at least one requirement.
“Save failed.” / “Draft save failed.”Create
Check
  1. Your licence is active and not at its limit (see below).
  2. You are still signed in.
Fix
Click Save as Draft, reload the page and try Create again. Send the time and folder name to info@smartestqa.ai if it fails again.
“Pipeline created successfully!” but there is no new pipeline in ScheduleCreate
Why
A pipeline needs a Start Page URL. Without one, only the test suite is created and the pipeline is skipped, but the success message still appears.
Fix
Add a Start Page URL (mark it default), then create the pipeline in Schedule from the suite named AI Generated Pipeline - YYYY-MM-DD.
My outline is gone after I switched folders or left the pageDraft
Why
The outline stays on your screen until you save a draft or create. A folder keeps only its saved draft, its preferences and its first file.
Fix
Run Analyze with AI again and click Save as Draft before you leave. See Drafts.
The outline is read-only and the buttons are disabledDraft
Why
It was already created, or the folder has requirements and no draft, so tab 2 lists them read-only.
Fix
Edit created requirements by selecting them in the tree. For new ones, run a new analysis.

Requirements and sub-requirements#

“Please fill Name and Description” / “Please enter a name” / “Please enter a description”Save
Fix
Both fields are required on main and sub-requirements. Fill them and save again. See Fields.
“Start Date cannot be in the future” / “Start Date cannot be after End Date” / “End Date cannot be before Start Date” / “Invalid date format. Please check your dates”Save
Why
Start Date must be today or earlier, and not after End Date. For a sub, the message starts with “Sub-requirement name:”.
Fix
Correct the date on the main requirement or on the sub named in the message (select it to see its Detail), then save.
“name could not be updated, please try again later”Save
Check
  1. Your session is still valid (reload in another tab).
  2. Someone else did not archive the requirement meanwhile.
Fix
Copy your text, reload, paste and save again. Write to info@smartestqa.ai with the requirement ID if it persists.
Generate is greyed out: “Please save the main requirement first”AI
Fix
Click Save on the main requirement, then Generate. See Generate sub-requirements.
“Requirement description is required” / “No sub requirements generated” / “Failed to analyze requirement” / “Please select at least one sub requirement”AI
Why
The AI needs the main requirement’s Description, and it may return nothing for a vague one. “Failed to analyze requirement” means the AI call failed (AI off, no key, provider error).
Fix
Write a description with the goal and the rules, save, and run Analyze again. Tick at least one proposal before Add. For AI errors see AI disabled and AI key.
A sub-requirement disappeared after savingSave
Why
It was deleted in the list before the save. Removing a sub and saving deletes it for good, with its test case links; it does not go to the Archive.
Fix
Recreate it with Add and link its test cases again (the test cases are still in Automate). See Saving.
“Company license limit has been reached…” / “Your license has expired…” / “Create process failed”Licence
Why
Your company’s licence can limit how many requirements you create. New requirements and documents count toward that requirement limit, and archived ones still count. An expired licence blocks every create.
Fix
See limit reached and licence expired, and ask an Admin to check the licence in Company Settings › Billing. Write main requirements with several subs rather than many separate mains.
The text failToFetchRequirements appears instead of a messageLoad
Why
Loading the requirement tree failed, and the message has no English text yet.
Fix
Reload the page. Check that a project is selected and you have access to it. If it repeats, write to info@smartestqa.ai.
Add is greyed out: “Please select a Sub Requirement first.” / “Please select a Sub Requirement first to delete.”Links
Why
Test cases link to sub-requirements. With the main requirement selected, the list shows all subs’ test cases read-only.
Fix
Click a sub in Sub Requirements, then use Add or Remove. A brand-new main needs at least one saved sub first. See Link a test case.
“This test case is already added to the Sub Requirement.”Links
Fix
Nothing to do; each test case is linked once per sub. To change its position, drag it in the list.
Automate is greyed out on a sub-requirementAI
Why
The sub is new (tag new) and not saved yet.
Fix
Click Save on the main requirement, then Automate.
“Requirement description is too short” / “Failed to analyze requirement” / “Please select at least one test case” / “Save failed”AI
Why
The sub’s description must be at least 10 characters; the AI call can fail like any AI request; Create needs at least one ticked test case.
Fix
Write a fuller description (condition and expected result), save, and run Analyze again. See Generate test cases.
“Scheduler synchronization failed” / “Some schedulers could not be updated”Pipelines
Why
The requirement was saved, but updating one or more pipelines failed.
Fix
Open those pipelines in Schedule and check their parameters, or change a link and save again to reopen the dialog. See How links reach pipelines.
Test Health shows a sub-requirement as not covered although it has a test caseCoverage
Why
Test Health counts a sub only when a linked scenario checks a result and passed its last run. A test case without an assertion, or one whose last run failed, does not count.
Fix
Add a check of the result to the test case in Automate and run it until it passes. See Test Health formulas.

AI assessment#

Analyze is greyed out on Assessment (AI)Assessment
Why
Either a sub-requirement is selected (“Sub-requirements are analyzed together with the main requirement. Please select the main requirement and click Analyze.”), or there are unsaved changes (“Please save your changes before analyzing with AI”).
Fix
Select the main requirement, click Save, then Analyze.
Dialog “AI Assessment”: “AI Assessment failed: …”Assessment
Why
The AI call failed. The text after “failed:” gives the reason: AI disabled, no key, a provider error, or an answer the server could not read (“…did not return JSON…”).
Fix
For AI disabled or key errors see above. Otherwise wait a minute and retry. If the message mentions JSON or a prompt, write to info@smartestqa.ai: it needs a fix on the SmartestQA side.
“n sub-requirement(s) not yet assessed:” / “Note: n sub(s) could not be scored by the LLM.”Assessment
Why
The AI left those subs out of its answer. Their old score, if any, stays.
Fix
Run Analyze again. If the same subs are skipped, make their descriptions clearer and shorter, or split a main requirement with very many subs.
The breakdown says “50% weight”, but the Quality Score is not the average of the two barsAssessment
Why
The Quality Score is the AI’s verdict on the main requirement; the first bar shows the same number and the second the mean of the sub scores, for information only. The “50% weight” wording is outdated.
Fix
Read the Quality Score and the per-sub scores. See Score Breakdown.

Tree, folders and archive#

“Name cannot be empty.” / “Module name is required.” / “A module with this name already exists”Folders
Fix
Type a name that no other module uses. Module names are shared with App Map and Automate. See Folders are modules.
A folder I created appeared as a module in App Map and AutomateFolders
Why
A folder directly under the project folder is a module. Create Folder with nothing selected creates it there (new_folder_n).
Fix
Rename it to a real module name. To turn it into a sub folder instead, an Admin moves it into another module folder, because that removes the module. See Folders are modules.
“A module folder stays directly under the project root…” / “Only an admin can move a module folder under another module, because it removes the module.”Folders
Why
Moving a module under another one removes the module from App Map and moves its Automate folder. That needs an Admin and a confirmation (“Make name a sub folder?”).
Fix
Ask an Admin to do the move, or move the module’s requirements instead of the folder.
“This module can’t be deleted yet: its folders still hold n item(s) in Analyze and m in Automate…” / “A module folder is deleted together with its module…”Folders
Why
A module folder is removed together with its module, and a direct delete is refused while its folders hold items.
Fix
As an Admin, archive the module folder from the tree (row menu › Delete): the module and its contents move to the Archive together. Or move the items out first. See Archive.
“You can only archive what you created…” / “Only an admin can archive a module…” / “You are not authorized to delete. Only admin or the creator can delete this.”Archive
Why
Users can archive only items where they created everything inside; modules need an Admin. The dialog’s Created by line shows who created what.
Fix
Ask an Admin or the creator. See Who can do what.
“Used as a template step in other test cases. Remove those steps first:”Archive
Why
Archiving a module also archives its Automate folder, and a test case in it is called as a template step by other test cases.
Fix
Open the listed test cases in Automate and remove or replace those steps, then archive again.
“Only the person who archived it or an admin can restore it.”Archive
Fix
Ask the person who archived it, or an Admin, to click Restore. After restoring, add the requirement to its pipelines again: restoring does not do that.
“Archiving failed.” / “Move failed” / “Delete failed.” / “Requirement update failed” / “Saving failed. Please try again.”Tree
Fix
Read the reason after the message if there is one (module rules are explained above). Otherwise reload the page and try again.
Search does not find a sub-requirement, or the Severity filter hides my documentsTree
Why
The tree contains main requirements, folders and documents only, so it searches their names and IDs. Documents have no severity.
Fix
Search for the main requirement, or for the sub’s ID. Clear the Severity filter to see documents. See Find requirements.

Documents and comments#

“This folder holds project documents only…” / “Requirements cannot be created inside the Documents folder.” / “Items cannot be moved in or out of the Documents folder.” / “This item can’t be archived.”Documents
Why
Documents is a special folder for files only. See Rules of the Documents folder.
Fix
Select a requirement folder for requirements and the AI wizard. Inside Documents you can still create sub folders and documents to organise files.
“name appears to be a corrupted or placeholder file (not a real .docx)…” / “Failed to create document. Please try again.”Documents
Why
The file has a .docx name but is not a Word file (often a web page saved as .docx), or the cached copy of the file is incomplete.
Fix
Open the original in Word, save it again as .docx, and attach that file. If the message mentions the cached content, select the file from your computer again.
“This file cannot be displayed as text. Please download to view.” / “Could not extract DOCX content” / “Download failed: Missing file data”Documents
Fix
Use Download File to open it locally. For a Word file, try Extract Text in Edit mode once more. A document created empty has no file to download.
“Comment cannot be empty” / “Couldn't load comments. Please try again.” / “Error creating comment” / I can’t edit someone’s commentComments
Fix
Type some text before Send; use Retry to reload. You can edit or delete only your own comments. See Comments.

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

info@smartestqa.ai