Problem and error codes

Every message of ReqSeq carries a stable code. The app, the command line, the API and MCP show the same codes.

Problem codes

A problem is a finding or a hint in the result of a command, for example of the workspace check, with a severity of error, warning or info. The command itself succeeded.

file.invalid-yaml

Cause: The YAML of a file (an element’s frontmatter, the workspace file, the metamodel) cannot be parsed, for example a wrong indentation, an unclosed frontmatter or an unresolved alias.

Remedy: Fix the YAML at the line and column the message gives. ReqSeq does not show or change the file until it parses.

file.conflict-markers

Cause: The file contains an unresolved Git merge conflict (lines starting with <<<<<<<, ======= or >>>>>>>).

Remedy: Resolve the conflict in Git and commit the result. ReqSeq never writes a file with conflict markers.

file.unreadable

Cause: A file or folder cannot be read, for example because of missing permissions.

Remedy: Check the permissions of the file or folder the message names.

file.faulty

Cause: An element has no version, because its file cannot be read the way its version is computed (for example a value without a normal form), or a JUnit test case is not enriched because its element has no current version.

Remedy: Fix the element’s file as the message says; then its version is computed and the test case can be enriched.

file.yaml-warning

Cause: The YAML parses, but the parser warns about it, for example about a tag or directive it does not know.

Remedy: Change the YAML at the line the message gives, so that it is plain YAML 1.2.

file.skipped

Cause: A file or folder is not read, because it is a symbolic link, not a regular file, has its extension in upper case (.MD), or is excluded by the workspace file.

Remedy: Replace a link by the real file, rename the extension to lower case (.md), or change the ignore globs of the workspace file if the file should be read.

element.invalid

Cause: An element file lacks what every element needs, for example an id that is a UUID version 4 in lower case or a type key.

Remedy: Correct the field the message names in the element’s frontmatter.

element.duplicate-id

Cause: Several element files have the same id, usually because a file was copied. A relation to that ID is ambiguous.

Remedy: Give the copy a new UUID. ReqSeq decides nothing and changes neither file.

element.duplicate-identifier

Cause: Two elements of the same type have the same identifier, so a reference by that identifier is ambiguous.

Remedy: Give one of them another identifier.

element.file-name-clash

Cause: Two element files in one folder have the same short file name, derived from the end of their UUIDs. This version does not raise it yet.

Remedy: Rename one of the files by hand. ReqSeq never renames files.

element.unknown-type

Cause: The element’s type is not in the metamodel. ReqSeq shows the element but only reads it.

Remedy: Use a type of the metamodel, or add the type to the metamodel.

element.unknown-property

Cause: The element has a property that its type in the metamodel does not define.

Remedy: Remove or rename the property, or add it to the type in the metamodel.

element.missing-required

Cause: A property that the element’s type requires has no value.

Remedy: Give the property a value. ReqSeq changes no file by itself.

element.wrong-value-kind

Cause: A property value does not have the kind the metamodel defines for it, for example text where a list or a relation target belongs.

Remedy: Correct the value so that it has the kind of the property.

element.status-not-allowed

Cause: The element’s status is not one of the statuses of its type.

Remedy: Set one of the statuses the message lists.

element.missing-status

Cause: The element’s type has statuses, but the element has none.

Remedy: Set one of the type’s statuses.

element.statement-without-text

Cause: A requirement has no text, but a value in the property with the meaning statement, which holds the supplier’s statement on an imported requirement and does not count to the version. So a change of the requirement written there gives no new version and outdates no evidence or relation.

Remedy: Put the requirement into the element text with element.update, and keep the statement property for the supplier’s statement.

relation.missing-target

Cause: A relation or an inline reference points to an ID that no element in the named repository has, for example because the target file was removed or its file cannot be read.

Remedy: Point the relation to an existing element, remove it, or fix the target’s file if the message names one.

relation.unresolved-link

Cause: A reqseq: link in the text or in a Markdown property names its target by a short ID or an identifier instead of a UUID, for example one written into the file by hand. Such a link counts for nothing, neither for outdated relations nor for the trace.

Remedy: Give the text or the property again with element.update, which resolves the short ID or identifier to the target’s UUID and version, or write reqseq:<uuid> yourself.

relation.not-a-link

Cause: The text of an element names an element with the scheme reqseq: outside a Markdown link and outside code, for example reqseq:N-6010df instead of [Title](reqseq:N-6010df). Only a Markdown link is a reference, so this one counts for nothing, neither for outdated relations nor for the trace.

Remedy: Write it as a Markdown link, [Title](reqseq:N-6010df), and give the text again with element.update, which resolves the target to its UUID and version. If it is no reference, put it in code (`reqseq:…`).

relation.inaccessible-target

Cause: The target of a relation is in a repository of the workspace that is not on this machine. This version does not raise it yet; it shows such targets as not accessible.

Remedy: Clone the repository where the workspace file expects it.

relation.not-allowed

Cause: A relation connects two element types that the metamodel does not allow for this relation kind.

Remedy: Use a relation kind that is allowed between the two types, or change the metamodel.

relation.outdated

Cause: The target of a relation or inline reference has changed since the relation stored its version, so the relation may need a review. A replaces item onto a core requirement from a requirement with a validity gives variant.core-changed instead; onto an element that is no core requirement (SR-041 AK8) or from a requirement without validity (SR-041 AK6) it stays relation.outdated.

Remedy: Check the source against the changed target, then confirm the hint (hint.confirm), which stores the target’s current version.

relation.target-superseded

Cause: A relation points to an element whose status marks it as superseded.

Remedy: Point the relation to the successor the message names, or confirm that the old target is still meant.

relation.not-found

Cause: The relation to remove does not exist, so nothing was removed.

Remedy: None needed; check the source and target if you expected the relation.

relation.version-added

Cause: The relation existed without a valid stored version; the target’s current version was stored now.

Remedy: None needed.

hint.not-confirmable

Cause: Only relation.outdated and variant.core-changed can be confirmed; other hints carry no hintId, and the ID names another hint or none. Also, a file whose version is held by a YAML alias or anchor cannot be changed in place. The hints on a core requirement changed or new since a variant’s baseline (variant.core-changed-since-baseline, variant.core-new-since-baseline) are refused when kind names them or ref names a variant that has them, since a new baseline of the variant settles them (SR-103 AK5).

Remedy: Other hints go away when what they report is fixed. For a file the message names, correct it by hand.

hint.not-found

Cause: No open hint has the given ID. It was confirmed already, or the relation, its target or the file changed since.

Remedy: List the open hints with hint.list and use one of their IDs.

trace.cycle

Cause: Relations of a deriving kind form a cycle, so the chain of the elements in it never ends.

Remedy: Remove or change one of the relations of the cycle the message lists.

trace.no-parent

Cause: An element of a type with the meaning requirement names no parent through a relation kind with the meaning derivation, so its chain ends without a parent (SR-022). In the standard model based-on has no meaning, so a decision is no parent.

Remedy: Give the element a parent with a relation of a deriving kind such as derives-from. To let a relation kind of your own count as derivation, give it the meaning derivation in your metamodel.

variant.core-changed

Cause: A core requirement that a variant requirement replaces has changed since the replacement stored its version (SR-045). It comes instead of relation.outdated for a replaces item (meaning replacement) from a requirement with a validity onto a core requirement, whatever the variant excludes, so the change gives one hint, not two. A superseded core requirement keeps the usual hints of a relation instead, relation.target-superseded and, when its content changed too, relation.outdated (SR-045 AK4).

Remedy: Check the replacing requirement against the change, then confirm the hint (hint.confirm). It stores the core requirement’s current version, and its title when both are in one repository (D-058); a variant in its own repository (D-020) gets the version only.

variant.superseded-in-validity

Cause: The validity of an element lists a variant element that is superseded.

Remedy: List the successor instead, or remove the entry.

variant.nested

Cause: A variant has validity entries, but a variant builds only on the core (D-020, SR-039 AK2/AK3).

Remedy: Remove the validity entries of the variant; a relation between variants is allowed.

variant.target-not-core

Cause: A replaces or exclusion entry names an element that is no core requirement, either one with a validity or one whose type has no validity property (a need, a package). It changes no view (SR-041 AK8, SR-042 AK7).

Remedy: Point the entry at a core requirement, or remove it; to retire an element for everyone, supersede it (SR-072).

variant.core-changed-since-baseline

Cause: A core requirement that the variant adopts has changed since the variant’s newest baseline (SR-103 AK1). The hint is at the variant and gives the version in the baseline and the current one.

Remedy: Check the variant against the change; the hint goes when a new baseline of the variant is created. It cannot be confirmed (D-042).

variant.core-new-since-baseline

Cause: A core requirement has come into the view of the variant since its newest baseline, because it is new, its exclusion was undone or its replacement removed (SR-103 AK7). The hint gives its current version.

Remedy: Check the variant against the change; the hint goes when a new baseline of the variant is created. It cannot be confirmed (D-042).

evidence.unknown-element

Cause: An evidence record or a test case names an element that the workspace does not have.

Remedy: Correct the element named in the record or test, or check that its repository is on this machine.

evidence.invalid-record

Cause: An evidence record or a JUnit file does not match its format.

Remedy: Fix the record at the place the message gives.

evidence.outdated

Cause: The newest evidence record of the element is for an older version of it.

Remedy: Verify the current version again, for example by running the test, so that a new record is written.

evidence.not-enriched

Cause: Test cases of a JUnit file name a requirement but carry no element version, so they give no evidence record.

Remedy: Enrich the file with evidence.enrichJunit right after the test run.

evidence.folder-missing

Cause: The evidence folder the workspace file names does not exist yet.

Remedy: None needed; ReqSeq creates it with the first record.

evidence.ambiguous-element

Cause: An evidence record or a test case names an element ID that several files share, so it is assigned to none of them.

Remedy: Give the copied element file a new UUID (see element.duplicate-id).

baseline.invalid

Cause: A baseline file cannot be read or does not match its format (ADR-0018), for example an element copy or a repository listed twice.

Remedy: Fix the file at the place the message gives.

baseline.repository-commit-differs

Cause: A repository the baseline names is checked out at another commit than the one the baseline stores for it. baseline.get reads the files on disk, not the baseline’s commits, so the warning names what was read. Without evidence that is the usual case, since the states compare the baseline with today’s files. With evidence the status is read from the evidence records on disk, for example a record committed after the baseline is missing when the repository is at an older commit.

Remedy: For the evidence status as it stood at the baseline, check out the commit the baseline names in that repository (the full commit is under repositories of the output) and run the command again. Otherwise none is needed.

filter.invalid

Cause: A saved filter cannot be read or does not match its format.

Remedy: Fix or save the filter again.

filter.duplicate-name

Cause: Two saved filters have the same name.

Remedy: Rename one of them.

metamodel.invalid

Cause: The metamodel is missing or faulty. An error makes the workspace read-only; a warning does not.

Remedy: Fix the metamodel files at the places the messages give and open the workspace again.

metamodel.meaning-unassigned

Cause: No relation kind of the metamodel has the meaning a command needs (for example derivation for the chain), so that part of the result is empty.

Remedy: Assign the meaning to a relation kind in the metamodel.

workspace.repository-missing

Cause: A repository of the workspace file is not on this machine. Its elements are missing from the results.

Remedy: Clone the repository where the workspace file expects it, if you need its elements.

workspace.metamodel-mismatch

Cause: A repository of the workspace is also a workspace of its own, and its metamodel differs from this workspace’s in the properties that count to the version (content). All repositories of a workspace are read with the workspace’s metamodel, so its elements get other versions here than in their own workspace, and relations and evidence read as outdated in one of the two. As info, its workspace file or metamodel cannot be read, so they are not compared.

Remedy: Give both workspaces the same metamodel, for example from a metamodel repository both include, or make the properties the message names count the same in both.

workspace.invalid

Cause: The workspace file does not match its format, for example a repository listed twice.

Remedy: Fix the workspace file at the place the message gives.

workspace.not-watched

Cause: ReqSeq cannot watch a folder for changes, for example because the system’s limit of watched folders is reached.

Remedy: Raise the limit (on Linux fs.inotify.max_user_watches) or restart ReqSeq after changes in that folder.

git.unavailable

Cause: Git cannot read a repository, because the git program is not on the PATH, the folder is not a Git repository, Git refuses a repository that another user owns (safe.directory), or its work tree sees none of the files.

Remedy: Install Git and put it on the PATH, check the repository, or add it to safe.directory in the Git configuration. ReqSeq only reads Git.

git.revision-missing

Cause: The commit to compare with is not in a repository, so its changes were not looked at.

Remedy: Fetch the commit, or deepen a shallow clone.

reqif.replaces-local

Cause: A repeated ReqIF import writes the delivery’s title, a property that does not count to the version, or the targets of a relation of a mapped kind into an element whose file holds other values there (SR-056); the import version cannot show a local edit of them (D-057). The message names the keys.

Remedy: If the local value should stay, change it in the source as well, or edit the element again after the import; Git shows the earlier value.

reqif.choice-unused

Cause: An entry of take or keep of reqif.import names no conflict of this delivery (SR-056 AK4), so it changes nothing.

Remedy: Name a conflict by its source IDENTIFIER or its element, as reqif.analyze lists them under conflicts.

reqif.edited-elsewhere

Cause: An object of a ReqIF file of ReqSeq has attribute values that differ from what its reqseq-markdown and reqseq-values give, so another tool changed it after the export (SR-052). reqif.import takes its readable attributes instead, through the mapping.

Remedy: Check the imported element; nothing else is needed. Edit elements in ReqSeq to keep the full round trip.

reqif.mapping-differs

Cause: A file of ReqSeq is imported without a mapping, and the saved mapping for its source names another source or tool (SR-052, SR-054). reqif.import uses that mapping as it is.

Remedy: If the mapping belongs to another source, rename or move it, or give the source in source.

Error codes

An error means that the command did not run or did not finish: the command line prints it and exits with a code other than 0, the API answers with an HTTP error, and MCP returns a tool error.

input.invalid

Cause: The input of the command does not match its schema, or names something the command cannot do, for example an unknown command.

Remedy: Correct the fields the message names; the reference page of the command lists its input.

ref.unknown

Cause: No element matches the given ID, short ID or identifier.

Remedy: Check the reference; a short ID may be outdated, and the message suggests the element meant when it can.

ref.ambiguous

Cause: The reference matches several elements, for example a short ID or an identifier that several elements have, or copies of a file that share a UUID.

Remedy: Give the full UUID of the element meant, or for copies of a file its repository or file, as the candidates in the error’s details show.

workspace.not-found

Cause: The folder has no reqseq-workspace.yaml, and no folder above it has one.

Remedy: Run the command inside a workspace, give --workspace, or create one with workspace.init.

workspace.read-only

Cause: The workspace is read-only because its metamodel is missing or faulty, so the command changes no file.

Remedy: Fix the metamodel files and open the workspace again.

element.read-only

Cause: The element can only be read, for example because its type is not in the metamodel.

Remedy: Use a type of the metamodel for the element, or add its type to the metamodel.

element.not-found

Cause: The element the command needs is not in the workspace. This version does not raise it yet.

Remedy: Check the reference and that the element’s repository is on this machine.

metamodel.meaning-unassigned

Cause: No relation kind of the metamodel has the meaning the command needs.

Remedy: Assign the meaning to a relation kind in the metamodel.

relation.not-allowed

Cause: The metamodel does not allow this relation kind between the types of source and target.

Remedy: Use an allowed relation kind, or change the metamodel.

variant.nested

Cause: The variant would get validity entries, but a variant builds only on the core (D-020, SR-039 AK2/AK3). element.create, element.update and element.bulkUpdate write nothing.

Remedy: Write the variant without validity entries; a relation between variants is allowed.

baseline.uncommitted-changes

Cause: A baseline needs a committed state, but files of the selected elements, their embedded files, the metamodel or the workspace file differ from HEAD or were never committed (SR-050 AK2); evidence records do not count.

Remedy: Commit those files with Git, or undo the changes, and create the baseline again.

baseline.exists

Cause: A baseline with this name exists, ignoring case and Unicode normal form; the error names its file and nothing was written (SR-050 AK6).

Remedy: Choose another name. ReqSeq never replaces a baseline.

reqif.invalid

Cause: The ReqIF file cannot be read or does not match the ReqIF format.

Remedy: Check the file, or export it again from the source tool. A packed delivery (.reqifz, a ZIP archive) is not read; unpack it and use the .reqif file inside.

reqif.unmapped

Cause: The ReqIF file has types, attributes, relation types or enumeration values that the mapping neither maps nor omits; details.unmapped is the same list as reqif.analyze gives, and no file was written (SR-055). Raised by reqif.import; reqif.analyze does not list it yet.

Remedy: Map or omit each entry with reqif.saveMapping or in the mapping file, and run the import again.

reqif.conflict

Cause: Elements of an earlier delivery were changed locally and the new delivery changes them too, and the import names no choice for them; details.conflicts lists them, and no file was written (SR-056 AK4).

Remedy: Name each conflict in take (the delivery wins) or keep (the local element stays), and run the import again.

git.unavailable

Cause: The command needs Git, but the git program is not on the PATH or the folder is not a Git repository; for a baseline also when a repository involved is not under Git or has no commit (SR-050 AK7).

Remedy: Install Git and put it on the PATH, or put the repository under Git and commit, or check the folder.

git.commit-not-found

Cause: The given commit is not available locally in any repository of the workspace.

Remedy: Fetch the commit, or deepen a shallow clone.

file.changed-on-disk

Cause: The file changed on disk since it was read, so writing it would overwrite someone else’s change; workspace.init also gives it when the workspace file or the metamodel file exists already.

Remedy: Read the element again and repeat the change; for workspace.init, choose a folder without these files.

file.faulty

Cause: A file the command needs cannot be read correctly, for example a faulty reqseq-workspace.yaml, an image to attach or a folder that cannot be read, a file to be replaced, or the file of an element selected for a baseline, which then has no version.

Remedy: Fix the file or its permissions as the message says, or move it away, and run the command again.

file.read-only

Cause: The folder of the file is not writable.

Remedy: Check the permissions of the folder.

file.not-regular

Cause: The path is a symbolic link or not a regular file, or a path above a folder to create is a file.

Remedy: Use a path to a regular file or folder.

file.folder-missing

Cause: The folder to write to does not exist or is in a repository that is not on this machine. Outside the workspace’s repositories ReqSeq creates no folders.

Remedy: Create the folder, or clone the repository.

command.not-implemented

Cause: The command is in the catalog, but this version does not implement it yet.

Remedy: Use a later version of ReqSeq.

internal

Cause: An error inside ReqSeq, or a call that its caller aborted.

Remedy: Repeat the call; if it fails again, report it with the message.