Matify/Project Blueprints for Jira

Troubleshooting

Error messages show a code (PBJ-…) and a reference ("ref"); a Failed, Partial or Blocked request shows its code on the request page. Send the code and the ref to support if a problem stays; the reference finds the matching log lines.

Error codes

CodeWhat you seeWhat to do
PBJ-POLICY-NAME"This name doesn't match the naming policy '…'" (with the expected format when the policy has a name template), or "A project with this name already exists."Change the name. Admins can test the policy under Policies → Try a key and name
PBJ-POLICY-KEYThe key breaks Jira's key rules or the naming policy (pattern, reserved keys or length); the message says which ruleChoose another key, or use the suggested key (Use …)
PBJ-KEY-TAKEN"The key ACME is already used by another project. Try ACME2 (suggested by Jira)." / "Another open request already reserves the key ACME. Choose another key."Choose another key or use the suggestion. A key reserved by an open request is released when that request is rejected, withdrawn, expired or cancelled. If a request is Failed with this code, the key was taken after approval; nothing was created; submit again with another key
PBJ-PERM-REQUEST"You don't have the 'Request projects (Project Blueprints)' permission. Your Jira admin can grant it in Global permissions." / "You don't have permission to browse users on this site."Ask your Jira admin to grant Request projects (Project Blueprints) to one of your groups (Jira settings → System → Global permissions). For the user-picker message, the admin grants Jira's Browse users and groups permission
PBJ-PERM-ADMIN"You need the Jira administrator permission (Administer Jira) for this part of Project Blueprints." / "Project Blueprints couldn't confirm your Jira permissions. Reload the page; if Jira asks you to allow access, accept it." / "An approver no longer has the Jira administrator permission. …" (the request is Blocked)Admin pages need Administer Jira. If the app couldn't confirm your permission, reload; if Atlassian's "Allow access" screen appears, accept it (see Common situations). If a request is Blocked because an approver lost Administer Jira, nothing was created; the requester submits again and a current admin approves
PBJ-PERM-PROJECT-ADMIN"You need to be an administrator of this project to request an owner change." (the Governance page itself says "You need project administrator permission to see this page")The Governance page is for people with Administer projects on that project, and for Jira admins
PBJ-PERM-OWNER"Only the project's owner can review it. Ask your Jira admin to change the owner if this should be you."Ask the owner, or ask a Jira admin to assign you as owner (Catalog → Assign owner) or to confirm a transfer
PBJ-REQUESTS-CLOSED"Project requests aren't open on this site yet. Ask your Jira admin."A Jira admin turns on Settings → Requests → Open requests
PBJ-FOUR-EYES"You can't approve your own request. Ask another Jira admin to approve it." / "The second approval must come from a different Jira admin."Ask another Jira admin. Sites with a single Jira admin can enable self-approval (Settings → Approvals, type ALLOW SELF-APPROVAL)
PBJ-STALE-PREVIEW"The approval is older than 24 hours. Cancel this request and ask the requester to submit a new one." / "Something changed since this request was approved (blueprint, schemes or members). …" / "The approval is older than 7 days. Leave the project as is, or create a new request." / "The number of remaining steps changed (now 3). Reload and confirm again." / at approval: a problem that blocks the request (see PBJ-SCHEME-MISSING)The first two stop an approved request before its project is created: it is Blocked and nothing was created; cancel it and have the requester submit again. For a partial project older than 7 days after approval, choose Leave as is and close, or have a new request submitted. If the remaining steps changed, reload and retry. A preview that changed before approval is not an error: the page shows "The preview changed"; review it and approve again
PBJ-BLUEPRINT-CHANGED"The blueprint version this request was submitted against is no longer available. Ask the requester to submit again." / "The blueprint version this request was approved against is no longer available." (the request is Blocked)The requester submits again (Request similar)
PBJ-BLUEPRINT-NOT-ACTIVE"This blueprint isn't available for requests anymore." / "This blueprint has no finished capture."Choose another blueprint. Admins: activate the blueprint once its capture is Ready, or re-capture
PBJ-BLUEPRINT-NOT-ALLOWED"You can't request projects from this blueprint. Ask your Jira admin to add one of your groups."A Jira admin adds one of your groups under Blueprints → Requesters & approvals → Allowed requester groups
PBJ-SCHEME-MISSINGA request is Blocked at approval or before provisioning starts: "… no longer exists. Re-capture the blueprint." (a scheme the blueprint uses was deleted), the key or name is now used by another project, or "The project lead isn't an active Jira user. …"For a missing scheme, admins Re-validate the blueprint to see what is missing, then Re-capture it. Nothing was created; the requester submits again (with another key, name or lead if needed)
PBJ-LEAD-INVALID"The lead must be an active Jira user. Choose another lead." (or owner)Choose an active user
PBJ-LEAD-NOT-CONFIRMED"Confirm that the chosen lead becomes project lead (project administrator)."Tick the lead confirmation before approving
PBJ-METADATA-INVALIDA required extra field is missing or doesn't match its format, or "The details are too long in total. Shorten the longest values."Fill in the field as its help text says
PBJ-CREATE-400"Jira didn't create the project: …" (for example the lead has no Jira access, or a scheme doesn't fit the project type)Nothing was created; the request is Failed. Fix the cause (lead's product access, blueprint schemes), then the requester submits again
PBJ-JIRA-403"Jira didn't allow Project Blueprints to read …" / "Jira didn't allow the app to create the project. Check that the app is installed with its permissions."In the first minute or two after installation this can happen while Jira finishes setting up the app's access: the catalog scan retries by itself; in a page, reload and try again. Later, check that the app is installed with all its permissions (Manage apps) and whether a Jira data security policy blocks app access to that project
PBJ-JIRA-404"Jira couldn't find … It may have been deleted."The object was deleted or moved to trash in Jira. For blueprints, re-validate and re-capture
PBJ-JIRA-5XX"Jira returned a server error. Project Blueprints will retry." / "The approval is recorded, but the provisioning job couldn't be queued. It will be retried automatically; you can also reload and retry." / "The request was redacted, but the project's governance property couldn't be updated. Try again."Wait and try again. Background work and provisioning steps retry by themselves; an approved request whose job couldn't be queued is queued again by the next daily run. If it persists, check Atlassian's status page and contact support with the ref
PBJ-RATE-429"Jira is rate-limiting apps right now. Project Blueprints will resume automatically." / "Project Blueprints has used this hour's share of Jira's rate limit for previews and checks on this site. Try again after 14:00 UTC."Background work and the catalog scan resume by themselves. In a page, the message says when to try again; see Large sites
PBJ-STEP-FAILEDOn the request page: "ACME was created, but not every step finished" with the reason, for example "Field 'Customer': …", "Step '…' kept failing (…)" or "Stopped by a Jira admin after the current step." Elsewhere: "Jira rejected the request for …"The request is Partial: follow the Partial provisioning runbook. If provisioning stopped before the project was created, the request is Failed or Blocked, nothing was created, and the requester submits again
PBJ-VERIFY-MISMATCHVerification found differencesOpen the request: the verification table lists every item. Done with notes needs nothing; for Partial follow the runbook
PBJ-LOCKED"This request is being changed right now. Reload in a moment." / "The request changed while you were approving it. Reload and check it again." / "A capture is already running for this blueprint." / "Another configuration change is in progress in Jira. Try again in a moment."Wait a moment, reload and check the request again
PBJ-KILL-SWITCH"Approvals and provisioning are paused by your Jira admin (kill switch)."A Jira admin turns the kill switch off in Settings → Safety. Approved requests that hadn't started then start by themselves (if their approval is less than 24 hours old); Partial requests can be retried
PBJ-LICENSE-INACTIVE"Project Blueprints' licence isn't active, so new requests and provisioning are paused. Your data stays readable."Renew the subscription in Manage apps. Approved requests that hadn't started are picked up by the daily job once the licence is active (if their approval is less than 24 hours old); Partial requests can be retried
PBJ-INVALID-STATEThe action doesn't fit the request's or blueprint's current state, for example "Only pending requests can be withdrawn.", "Archived blueprints can't be reactivated. Re-capture or create a new blueprint.", "Wait until the capture has finished before activating this blueprint.", "The guided test has already been used on this site.", "This request has expired.", "Only partially provisioned requests can be resumed."Reload to see the current state; the message says what is possible
PBJ-INVALID-INPUT"The request was not valid. Reload the page and try again." Also: a typed confirmation doesn't match, a reject reason is shorter than 10 characters, a setting is out of range, "Team-managed projects can't be blueprints …", "Only software and business projects can be blueprints in this version …"Reload, or correct the input as the message says. Team-managed: create a team-managed blueprint from a built-in template instead
PBJ-NOT-FOUNDThe request, blueprint or policy no longer exists, or "isn't yours"; when capturing: "Jira couldn't find that project."It was deleted, pruned by retention, or belongs to someone else. Reload the list
PBJ-STORAGE"The approved plan is missing, so nothing was created. Ask the requester to submit a new request." (or, if the project exists, "… so the remaining steps can't run. Leave the project as it is.") / "The capture data expired; capture again."Follow the message. If it repeats, contact support with the ref
PBJ-UNKNOWNAn unexpected errorRetry. If it keeps happening, download diagnostics (Health) and contact support with the ref
PBJ-UI-BRIDGE"Project Blueprints could not reach its backend. Reload the page and try again."Reload. If it persists, check your connection and Atlassian's status page, then contact support

Common situations

The catalog is empty right after installation. The scan starts at least 90 seconds after installation and fills the catalog project by project. Overview shows "Reading your projects". On large sites the first full catalog can take hours. If nothing happens for a long time, check Health → Catalog scan for the phase and errors.

A project created outside the app isn't shown yet. The app re-reads a project about a minute after Jira's project event, and Atlassian sometimes delivers events a few minutes late. The weekly reconcile catches anything missed; Health → Run reconcile now starts one at once (at most once an hour).

The creator of an "Outside the gate" project is unknown. The app looks up the creator in Jira's audit log. If the audit log has no matching entry, or the app can't read it (Health → Probes), the creator shows as unknown.

A requester sees no blueprints. No active blueprint allows one of their groups. Check the blueprint's Allowed requester groups (empty means everyone with the request permission) and that the blueprint is Active.

The request form says requests aren't open. Turn on Settings → Requests → Open requests, and grant Request projects (Project Blueprints) to the requester's group.

Atlassian's "Allow access" screen appeared. Normally the app checks permissions itself and no consent is needed. If Jira's permission-check API fails, the app falls back to checking as the user, which can show this screen once. Accepting it is safe. Health → Permission checks shows "Fallback in use"; if it stays on, contact support.

The approve button is missing or greyed out. It is missing when you are the requester (four-eyes), you gave the first of two approvals, the request isn't pending any more, the kill switch is on or the licence is inactive; the decision panel says which. It is greyed out while the preview is out of date (choose Build a fresh preview) or a confirmation is still missing (lead confirmation, typed key); the panel says what is needed.

The preview says it is stale or out of date. The blueprint or a referenced scheme, role, group or user changed since the preview was built. Choose Build a fresh preview, review it and approve again.

Provisioning seems stuck or paused. Open the request: the step list shows which step waits. Common causes: Jira is rate-limiting apps (the step waits and retries by itself; after 5 attempts the request stops as Partial, or as Failed if the project doesn't exist yet; Health shows rate limit pressure), the kill switch is on, or the licence is inactive. Approved requests whose job didn't start are re-queued automatically once a day, and at once when the kill switch is turned off. The next daily run restarts a provisioning that has made no progress for at least an hour; after 24 hours without progress it stops as Partial (project exists) or Blocked (no project yet), so a request never stays in Provisioning for good.

Someone's admin rights changed, but the pages haven't caught up. Admin read views cache the Administer Jira check for up to 5 minutes, and the request form caches the request permission for up to 5 minutes. Actions that change requests, blueprints, policies, settings or the catalog check again at once, so a person who lost the permission can't approve, change settings or submit.

The tracking work item wasn't created. Check Settings → Requests (tracking project and work type), that the work type exists in the tracking project and that the project accepts new work items. Jira data security policies can block app access to work items. The request continues without a tracking work item in every case.

Field contexts show "not applied". A field with more than one non-global context for the reference project can't be assigned (Jira's API accepts one context per field and project). Locked fields and global contexts are never applied. Assign them in Jira if needed. See Known limitations.

No board was created. Project Blueprints doesn't create or copy boards, filters or board configuration. Set boards up in Jira after the project is created.

Ledger: "Integrity check failed". The page shows the first entry that doesn't verify. Treat this as a security issue: don't delete app data, download diagnostics and email support@matifyapps.de with "security" in the subject.

Ledger: "Integrity check incomplete". The check on the Ledger page didn't finish within one page request; each run starts again from the first entry. The weekly background check goes through the whole ledger in parts; Health → Permission checks shows its result (Ledger, Ledger last checked).

What to send to support

  1. Health → Download diagnostics (no names, e-mail addresses or project content).
  2. The error code and ref.
  3. For requests: the request ID and the ledger sequence numbers.
  4. What you did and what you expected.

Email support@matifyapps.de, or use the form or tracker on the support page. Never post account IDs or project content in the public tracker.