Troubleshooting and FAQ¶
Answers to the questions that come up most often, from upload errors to rules that didn't fire. Each answer says what's happening and what to do about it. If your question isn't here, ask your DV Forge contact.
Upload errors¶
What do the CLI's exit codes mean?¶
dvforge upload always exits with one of these codes, so your CI can tell a mistake in the
command from a server problem:
| Code | Meaning | What to do |
|---|---|---|
0 |
Success, including --dry-run. |
Nothing. |
2 |
Usage error: a bad flag, a missing or unreadable JUnit file, or a JUnit file DV Forge refuses to read. Nothing was sent. | Fix the command; the message says what's wrong. |
3 |
Authentication error: the server answered 401 or 403. |
See the next two questions. |
4 |
Any other error: a 4xx answer, or a network or server error that outlasted the retries. |
Read the message. If it's a network or server error, rerun the same command later. |
130 |
You interrupted the upload. | Rerun the same command to resume. |
Rerunning the same command is always safe: logs already stored aren't sent again, batches
already ingested are recognized and skipped, and the regression is updated rather than
duplicated. The CLI retries network errors, 429 and 5xx answers five times with
increasing waits before it gives up with code 4.
401 (exit code 3)¶
The token is missing, mistyped, revoked or expired. The CLI adds check DVFORGE_TOKEN
(project tokens look like dvf_<8hex>_<secret>) and --project. Check that DVFORGE_TOKEN is
set in the CI job's environment and holds the whole secret. If the token was revoked or has
expired, ask a project admin for a new one. See
API tokens.
403 (exit code 3)¶
You reached the project, but the upload isn't allowed:
requires member role. The token has only thereadscope. Uploads needingest:write.this project ingests through its data plane; point the uploader at it. Your project sends results through a data plane, so DV Forge refuses direct uploads. SetDVFORGE_URLto your data plane's address. See Data planes.project … is not bound to this data plane. You uploaded through a data plane that your project doesn't use. PointDVFORGE_URLathttps://api.daruur.cloud, or ask a project_admin to bind the project to that data plane.
404 (exit code 4)¶
Most often project not found: --project (or DVFORGE_PROJECT) names a project the token
doesn't belong to, or that you can't see. A project token needs no --project at all; if
you pass one, it must be the token's own project. Also check DVFORGE_URL: it should be
https://api.daruur.cloud, or your data plane's address, with no extra path.
Tip
If you don't set DVFORGE_URL, the CLI uses http://localhost:8000, and the upload
fails with connection errors after its retries. Always set it in CI.
413 (exit code 4)¶
A log is too large for DV Forge to accept: over 256 MiB uncompressed, or over 64 MiB after
compression. The CLI skips logs larger than --max-log-mb (256 by default) with a warning
before it uploads anything, so a 413 usually means a log that's under that size but
doesn't compress well. Lower --max-log-mb, or send logs only for failing jobs with
--only-failing-logs.
Other 4xx answers (exit code 4)¶
The message names the problem. One you might see is sha256 does not match content: a
log file changed while it was being uploaded. Rerun the command once the simulation has
finished writing it.
The CLI says a log match is ambiguous¶
warning: <test>: ambiguous log match (…); no log attached means several log files fit
the test equally well, so the CLI attached none. Give the log files names that contain the
test name and the seed, or point to each test's log file from the JUnit report. See
The dvforge CLI.
Regressions¶
My regression still shows live¶
A regression stays live until its upload completes. That happens when the CLI was run
with --no-complete, or when it stopped before its last step.
To complete it, rerun the upload without --no-complete, with the same --external-id.
Batches already ingested are skipped, and the regression is marked complete.
Completing matters:
- Rules on the A regression finishes trigger run only when a regression completes.
- Recurrence is judged against complete regressions, so a regression left
livedoesn't count as a run that "didn't hit" a signature.
If the CLI printed status: complete (spooled on the data plane), DV Forge was unreachable
and your data plane queued the completion. It goes through once DV Forge is back.
Rerunning an upload for a regression that's already complete reopens it: it's live again
until the rerun finishes. See Regressions and failures.
My new regression doesn't appear on Failures¶
- Reload the page: the Failures list doesn't refresh by itself.
- Check the project switcher. The regression is in the token's project, which may not be the project you have selected.
- DV Forge processes uploads in the background, so signatures can appear a moment after the
CLI finishes. Add
--waitto make the CLI wait for processing.
The log viewer says my data plane didn't answer¶
For a project that uses a data plane, raw logs stay in your network. DV Forge fetches a log
from the data plane only when someone opens it. If the data plane doesn't answer, the log
page shows: "This log lives in your data plane, which didn't answer. Check that it is
running and can reach DV Forge, then reload." (The API answers 504.)
- If the data plane hasn't checked in for 90 seconds, DV Forge treats it as offline and answers at once.
- If it's online but doesn't return the log within 30 seconds, the request times out.
Check the data plane's state on the Data planes page, make sure it's running and can reach DV Forge, then reload. A log is always fetched from the data plane that stored it at upload time, even if the project has since moved to another one. See Data planes.
The log viewer shows up to about 2 million characters of a log and marks longer ones as truncated.
A job has no log link¶
No log was attached to it at upload: the CLI found no matching file, found several (see
The CLI says a log match is ambiguous), skipped it
as too large, or you used --no-logs or --only-failing-logs.
Signatures¶
Why are two failures in the same signature, or in different ones?¶
DV Forge files a failure by the fingerprint of its headline, the first error or fatal message in its log, after the project's masks blank out values that vary between runs.
- Same signature: the two headlines reduce to the same text, even if the tests, seeds or regressions differ. That's the point: the same bug is one signature.
- Different signatures: the headlines differ after masking. Often a value that changes from run to run (an address, a transaction id, a path) isn't masked, so one bug splits into several signatures.
Open a signature and expand Normalized template to see the text its failures reduced to. To change the grouping:
- Merge signatures that are the same bug, or split one that mixes two. See Merge, split and suggestions.
- Add a mask so a varying value stops splitting signatures. That re-buckets the whole project; a project admin can preview the effect first. See Bucketing settings.
If an unrelated error appears earlier in the log than the real one, it becomes the headline. Simulators and log formats explains how headlines are chosen.
Why did a resolved signature come back?¶
It Regressed: it was hit again in a regression that started after someone marked it Resolved. DV Forge moves it to Regressed and notifies its assignee and watchers. Regressions that started before it was resolved, even if uploaded later, don't reopen it.
Often the fix hasn't reached the branch that failed, or it didn't fix every cause. Check which regression hit it in the signature's History, then move it to whichever status fits.
The recurred badge is different: it means the signature came back after a complete regression on the same branch didn't hit it. Recurrence is counted but doesn't change the status. See the Glossary.
Why can't I change a signature's status?¶
- Your role. Changing status needs triager; waiving needs project_admin.
- The signature is merged. Triage happens on the surviving signature. The page links to it.
- The change isn't allowed from here. Move to… offers only allowed changes: a Resolved signature reopens to Untriaged or Investigating; Not a bug, Muted and Waived reopen to Untriaged; nobody can choose Regressed.
- It needs more information. Tracked needs a bug reference and Waived needs a reason; the dialog asks for them.
See Working a signature.
Some signatures in my bulk action failed¶
A bulk action covers up to 200 signatures. Each one succeeds, is unchanged (it was already in that state), or fails with its own reason, for example a status change that isn't allowed from its current status, or a signature that has been merged. The successes are saved even when others fail. See The triage queue.
Rules¶
Why didn't my rule fire?¶
Work through these in order:
- Is it enabled? Disabled rules never run.
- Did its trigger happen after you saved it? Rules act on events (a new signature, a
hit, a recurrence, a regressed signature, a finished root-cause run, a completed
regression).
They don't go back over signatures that already exist. Use the rule's preview to see
what it would match today. A regression finishes fires only when a regression
completes; see My regression still shows
live. - Is the signature in scope? Branch patterns are case-sensitive, and a regression
uploaded without
--branchnever matches a rule scoped to branches. A saved-search scope must also match. - Does the signature match the filter? Relative conditions such as "within 7 days" are measured from the regression's time, not from now.
- Did an earlier rule stop it? Rules run in order. If an earlier rule with Stop processing matched, later rules skip the signature. Later rules also see earlier rules' changes, which can make a match fail.
- Did it match but do nothing? Open the Rule run log. Each action shows applied, skipped or failed, with the reason: for example the signature was already in that status, the status change isn't allowed from its current status, a person had already chosen its classification, or Run the root-cause agent reached its limit of 10 runs per rule in any 24 hours.
If the signature has since been merged, the rule acts on the surviving signature. See Triage rules.
Root-cause agent¶
Why is Run root-cause disabled?¶
The button reads "Needs a scenario mapping" when the signature isn't linked to a scenario the agent can run. Root-cause runs currently work on signatures linked to one of the built-in scenarios on the Scenarios page; running the agent on failures from your own designs isn't available yet. Starting a run also needs the member role. See Root-cause agent.
The run finished, but the status didn't change¶
That's by design: the agent proposes, and a person decides. The signature shows Root-cause hypothesis ready. Review the run, then select Confirm root cause to move it to Root-caused (triager role). To confirm automatically, write a rule on the A root-cause run finishes with a hypothesis trigger that sets the status. See Runs and hypotheses.
Comments, attachments and notifications¶
My attachment won't upload¶
- Over 10 MB. Attachments are limited to 10 MB each.
content isn't image/png(or another image type, or PDF). The file is named or typed as an image or PDF but isn't a complete one. Re-export it, or attach it under its real type.empty file. The file has no content.- No upload control. Attaching needs the member role, and merged signatures don't take attachments: add them to the surviving signature.
Files a browser would display or run, such as HTML or SVG, are accepted but stored as plain downloads.
I'm not getting notifications¶
Notifications are in-app only today, under the bell at the top of the sidebar, which checks every 60 seconds. You're notified only when:
- someone else assigns a signature to you (not when you assign yourself),
- a signature you watch or are assigned regresses,
- a root-cause run you started, or one on a signature you watch or are assigned, finishes or fails,
- a rule's Notify action names you, the assignee or the watchers.
New signatures and status changes don't notify anyone unless a rule says so. Select Watch on the signatures you care about, or ask a triager to add a Notify action to a rule. You don't see notifications from organizations you no longer belong to. See Notifications.
Access¶
I only see a project called default¶
That's the personal organization DV Forge created at your first sign-in. You haven't been added to your team's organization yet. Adding people is done by your DV Forge contact today; ask your organization's admin to arrange it. See How people get in.
A link a colleague sent me shows "not found"¶
You don't have access to the project it belongs to. DV Forge answers "not found" rather than "forbidden" for anything in a project you can't see, so ids never reveal what exists in other organizations. Ask to be added to that organization.
My API token works for uploads but not for comments¶
API tokens can't do things that need a person: comment, attach files, watch signatures, save
searches or read notifications. Those requests get 403. See
Permissions.