Nullgap.dev Docs

Help

Getting help

Find out why a review, a pentest or a webhook delivery failed, and what to send Nullgap when you need to ask.

Most questions about a run can be answered from what Nullgap already shows you: the run's log, the reason a review was skipped, the background jobs list, and a webhook's delivery records. This page says where each one is, and what to include when you do need to contact Nullgap.

#First, look here

What went wrongWhere to look
A pull request was not reviewedThe review's skip reason, on PR reviews
A review or a pentest failed, or stopped earlyIts Log tab
A run seems stuck, or a fix or threat model never finishedSettings, Background jobs (admins)
Your endpoint is not receiving webhooksThe webhook's Deliveries, on Integrations
An API call was refusedThe code and message in the error body
A setting changed, or access changed, and you do not know whyThe audit log

#A pull request was not reviewed

Open PR reviews. A pull request that Nullgap saw but did not review is listed as Skipped, with the reason next to it. The same text is in skipReason on the review.

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reviews?status=skipped&limit=20"
Skip reasonWhat to do
"PR reviews are not enabled for this repository"Switch reviews on for the repository, under Repositories
"Draft pull request"Mark it ready for review, or ask for a review by hand
A filter is namedChange the filter. See filters
"This change touches ... files; reviews cover up to ..."Split the change into smaller pull requests
"No active trial or subscription..."Start the trial or agree a plan. See usage
"The pooled review quota for this month is used up..."Turn on extra reviews or add seats. See review quota
"This workspace has reached its monthly usage limit..."See the monthly usage ceiling
"This workspace is suspended..."Contact Nullgap. Help still works in a suspended workspace

If the pull request is not listed at all, Nullgap never received the event. Check that the repository appears under Repositories, that the code-host connection is still in place, and for connections with their own webhook that the webhook exists on the code-host side. See connecting your code.

A review asked for by hand, from the console or with the review command in a pull request comment, skips the "not enabled", "draft" and filter checks. See comments and commands.

#A review or a pentest failed

Open the run and choose the Log tab. The log is a list of timed lines at three levels, info, warn and error, describing what the run did and where it stopped.

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests?limit=5"

Take the id of the run from the list, and read its log at GET /api/orgs/:org/pentests/:id/logs (or /reviews/:id/logs for a review). Each line looks like this:

{ "at": "2026-11-16T09:31:12.000Z", "level": "warn", "message": "This review is incomplete: part of the change could not be reviewed. Re-run it before relying on the result." }

What the common endings mean:

You seeMeaningWhat to do
A review that says it is incompletePart of the change could not be reviewed. The check is neutral, never a passRun the review again
"Zero data retention could not be confirmed..."The run was stopped for a privacy reason and is not retried automatically. See AI processingStart it again later; contact Nullgap if it repeats
422 checkout_failed from the API, or a run that fails while fetching the codeNullgap could not fetch the code: the connection lost access, or the branch or commit no longer existsCheck the connection and the ref, then run again
"Live testing of ... cannot start" when starting a pentestThe sign-in check for a live target failed before anything was chargedFix the test account or sign-in steps. See live testing
A failed pentestIts credits are refundedStart a new pentest from Pentests

A run's log is deleted with the run, by retention or erasure.

#Background jobs

Every review, pentest, fix run and threat model build is carried out by a background job. Admins can see them under Settings, Background jobs, with a Status, the number of Attempts, the Last error and When.

StatusMeaning
queuedWaiting to start, or waiting for its next attempt (nextAttemptAt)
runningIn progress
completedDone
failedEnded with an error that is not retried automatically
cancelledCancelled by a person, or replaced by a newer run
deadFailed for a passing reason, was retried automatically, and gave up after the last attempt

kind is one of review, pentest, remediation (a fix run) or context (a threat model build), and refId is the id of the review, pentest, fix run or application it belongs to.

With an API key that has the admin scope:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/jobs?status=dead"
{
  "items": [
    {
      "id": "job_2k9m4x",
      "kind": "review",
      "refId": "rev_3m8k2p",
      "status": "dead",
      "attempts": 3,
      "error": "Nullgap AI did not return an answer",
      "createdAt": "2026-11-16T09:30:00.000Z",
      "startedAt": "2026-11-16T09:41:07.000Z",
      "finishedAt": "2026-11-16T09:44:52.000Z",
      "nextAttemptAt": null
    }
  ],
  "total": 1
}

#Retrying a job

An admin can start a failed or dead job again with Retry. Through the API it is POST /api/orgs/:org/jobs/:id/retry, which an admin-scope key may call; see the background jobs reference.

  • Only a job that is failed or dead can be retried. Anything else answers 409 not_retryable.
  • A pentest job cannot be retried. A failed pentest was refunded, so running it again here would skip payment. The console shows "Refunded. Start a new pentest."; start one from Pentests.
  • A retry is written to the audit log as job.retried.

If the same job dies again with the same error, retrying further will not help: note the job id and the error, and contact Nullgap.

#Webhook deliveries

On Integrations, each outbound webhook has a Deliveries list with its most recent deliveries, and a Send test button that sends a ping event.

FieldMeaning
typeThe event, or ping for a test
okWhether your endpoint accepted it
statusThe HTTP status your endpoint answered with, or null if there was no answer
errorWhy it failed, in plain words
attemptsHow many times it has been tried
nextAttemptAtWhen the next attempt is due, while a failed delivery is still being retried

Reading the list through the API needs the admin scope:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/webhooks"

How to read a failing delivery:

  • A status of null means Nullgap could not reach your endpoint at all: DNS, TLS, a firewall, or a time-out.
  • A 4xx or 5xx status came from your endpoint. A 401 or 403 usually means the signature check on your side is failing: see webhooks for how to verify it.
  • A webhook that shows as disabled with a reason was switched off; fix the cause, then switch it on again.

For deliveries from Jira or Slack to Nullgap, see Jira and Slack.

#API errors

Every error from the API has the same shape, and every response carries an X-Request-Id header:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the admin scope",
    "requestId": "req_Zk3vQ1x8LmPa"
  }
}
Status and codeMeaning
401 unauthenticatedNot signed in, or the session has ended
401 invalid_api_key, expired_api_keyThe key was revoked or rotated, or has passed its expiry
403 insufficient_scopeThe key's scope does not allow this. See API keys
403 forbiddenYour role does not allow this, or it is an action no API key may do
403 step_up_requiredThe action needs a fresh second-factor check. See the step-up check
403 mfa_requiredThe organisation requires a second factor and your account has none
403 sso_requiredThe organisation requires single sign-on
403 org_suspendedThe workspace is suspended: reading works, changes do not
404 not_foundThe thing does not exist. An organisation you are not a member of answers the same way
402 usage_limit, no_credits, payment_requiredSee usage
429 rate_limitedToo many requests. Wait a minute
500 internalSomething went wrong on Nullgap's side. Keep the requestId

More on errors, paging and rate limits is under API overview.

To check that the service is reachable at all:

curl -s "$NULLGAP_URL/healthz"

It answers {"ok":true} without sign-in.

#Contacting Nullgap

Open Help in the console and send a request from there. How requests, replies and support access work is on the support channel. The Help page also shows the support e-mail address of your installation, where one is set.

The console attaches the page you were on, the finding, review or pentest you had open and the reference of the last request that failed, unless you untick them. If you write from somewhere else, include the following, so that the first reply can be an answer rather than a question:

IncludeWhere to find it
The request idrequestId in the error body, or the X-Request-Id response header. It starts with req_. In the console, copy it from the failed request in your browser's network tools
Your organisation's slugThe first part of the console address after the host: acme in /acme/findings
The run idThe id of the review (rev_...), pentest (pen_...), fix run or job concerned, from its address or from the API
The time it happenedWith the time zone, or in UTC
What you expected, and what happened insteadIn a sentence or two
The relevant log lines or the skip reasonCopied as text

Do not send secrets: no API keys, SCIM tokens, webhook signing secrets, recovery codes or test-account passwords. Nullgap never needs them to investigate, and the request id is enough to find the request. If a secret has been exposed, rotate it first.

Nullgap staff can see workspace-level information and the status of your jobs. They do not have your repository. What they can see of your findings, and how every such read is recorded in your audit log, is described under who at Nullgap can see what. Support staff answering a request cannot open your findings, reviews or pentests unless an admin allows it for a limited time.

#Reporting a security issue in Nullgap

If you believe you have found a vulnerability in Nullgap itself, as opposed to a finding Nullgap reported about your code:

  • Report it privately: through Help in the console with the category Security concern, or through the contact given in your agreement with Nullgap. Say at the start that it is a security report.
  • Do not post it in a public issue tracker, a public channel or a pull request.
  • Include what you observed, the steps to reproduce it, the request ids and times involved, and your organisation's slug.
  • Do not include other people's data. If you came across data that is not yours, say so and stop there.

If the issue is that your own audit log does not verify, see if something does not verify.

Nullgap documentation