Note: Issue forms are currently in beta and subject to change.
Required top level key name
is missing
The template does not contain a name
field, which means it is not clear what to call your issue template when giving users a list of options.
Example of "required top level key name
is missing" error
description: "Thank you for reporting a bug!"
...
The error can be fixed by adding name
as a key.
name: "Bug report"
description: "Thank you for reporting a bug!"
...
key
must be a string
This error message means that a permitted key has been provided, but its value cannot be parsed as the data type is not supported.
Example of "key
must be a string" error
The description
below is being parsed as a Boolean, but it should be a string.
name: "Bug report"
description: true
...
The error can be fixed by providing a string as the value. Strings may need to be wrapped in double quotes to be successfully parsed. For example, strings that contain '
must be wrapped in double quotes.
name: "Bug report"
description: "true"
...
Empty strings, or strings consisting of only whitespaces, are also not permissible when the field expects a string.
name: ""
description: "File a bug report"
assignees: " "
...
The error can be fixed by correcting the value to be a non-empty string. If the field is not required, you should delete the key-value pair.
name: "Bug Report"
description: "File a bug report"
...
input
is not a permitted key
An unexpected key was supplied at the top level of the template. For more information about which top-level keys are supported, see "Syntax for issue forms."
Example of "input
is not a permitted key" error
name: "Bug report"
hello: world
...
The error can be fixed by removing the unexpected keys.
name: "Bug report"
...
Forbidden keys
YAML parses certain strings as Boolean
values. To avoid this, we have explicitly forbidden the usage of the following keys:
y
, Y
, yes
, Yes
, YES
, n
, N
, no
, No
, NO
, true
, True
, TRUE
, false
, False
, FALSE
, on
, On
, ON
, off
, Off
, OFF
The error can be fixed by removing the forbidden keys.
Body must contain at least one non-markdown field
Issue forms must accept user input, which means that at least one of its fields must contain a user input field. A markdown
element is static text, so a body
array cannot contain only markdown
elements.
Example of "body must contain at least one non-markdown field" error
name: "Bug report"
body:
- type: markdown
attributes:
value: "Bugs are the worst!"
The error can be fixed by adding non-markdown elements that accept user input.
name: "Bug report"
body:
- type: markdown
attributes:
value: "Bugs are the worst!"
- type: textarea
attributes:
label: "What's wrong?"
Body must have unique ids
If using id
attributes to distinguish multiple elements, each id
attribute must be unique.
Example of "body must have unique ids" error
name: "Bug report"
body:
- type: input
id: name
attributes:
label: First name
- type: input
id: name
attributes:
label: Last name
The error can be fixed by changing the id
for one of these inputs, so that every input
field has a unique id
attribute.
name: "Bug report"
body:
- type: input
id: name
attributes:
label: First name
- type: input
id: surname
attributes:
label: Last name
Body must have unique labels
When there are multiple body
elements that accept user input, the label
attribute for each user input field must be unique.
Example of "body must have unique labels" error
name: "Bug report"
body:
- type: textarea
attributes:
label: Name
- type: textarea
attributes:
label: Name
The error can be fixed by changing the label
attribute for one of the input fields to ensure that each label
is unique.
name: "Bug report"
body:
- type: textarea
attributes:
label: Name
- type: textarea
attributes:
label: Operating System
Input fields can also be differentiated by their id
attribute. If duplicate label
attributes are required, you can supply at least one id
to differentiate two elements with identical labels.
name: "Bug report"
body:
- type: textarea
id: name_1
attributes:
label: Name
- type: textarea
id: name_2
attributes:
label: Name
id
attributes are not visible in the issue body. If you want to distinguish the fields in the resulting issue, you should use distinct label
attributes.
Labels are too similar
Similar labels may be processed into identical references. If an id
attribute is not provided for an input
, the label
attribute is used to generate a reference to the input
field. To do this, we process the label
by leveraging the Rails parameterize method. In some cases, two labels that are distinct can be processed into the same parameterized string.
Example of "labels are too similar" error
name: "Bug report"
body:
- type: input
attributes:
label: Name?
- type: input
id: name
attributes:
label: Name???????
The error can be fixed by adding at least one differentiating alphanumeric character, -
, or _
to one of the clashing labels.
name: "Bug report"
body:
- type: input
attributes:
label: Name?
- type: input
attributes:
label: Your name
The error can also be fixed by giving one of the clashing labels a unique id
.
name: "Bug report"
body:
- type: input
attributes:
label: Name?
- type: input
id: your-name
attributes:
label: Name???????
Checkboxes must have unique labels
When a checkboxes
element is present, each of its nested labels must be unique among its peers, as well as among other input types.
Example of "checkboxes must have unique labels" error
name: "Bug report"
body:
- type: textarea
attributes:
label: Name
- type: checkboxes
attributes:
options:
- label: Name
The error can be fixed by changing the label
attribute for one of these inputs.
name: "Bug report"
body:
- type: textarea
attributes:
label: Name
- type: checkboxes
attributes:
options:
- label: Your name
Alternatively, you can supply an id
to any clashing top-level elements. Nested checkbox elements do not support the id
attribute.
name: "Bug report"
body:
- type: textarea
id: name_1
attributes:
label: Name
- type: checkboxes
attributes:
options:
- label: Name
id
attributes are not visible in the issue body. If you want to distinguish the fields in the resulting issue, you should use distinct label
attributes.
Body[i]: required key type is missing
Each body block must contain the key type
.
Errors with body
will be prefixed with body[i]
where i
represents the zero-indexed index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: required key type is missing" error
body:
- attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
The error can be fixed by adding the key type
with a valid input type as the value. For the available body
input types and their syntaxes, see "Syntax for GitHub's form schema."
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
Body[i]: x
is not a valid input type
One of the body blocks contains a type value that is not one of the permitted types.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: x
is not a valid input type" error
body:
- type: x
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
The error can be fixed by changing x
to one of the valid types.
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
Body[i]: required attribute key value
is missing
One of the required value
attributes has not been provided. The error occurs when a block does not have an attributes
key or does not have a value
key under the attributes
key.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: required attribute key value
is missing" error
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
- type: markdown
The error in this example can be fixed by adding value
as a key under attributes
in the second list element of body
.
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
- type: markdown
attributes:
value: "This is working now!"
Body[i]: label must be a string
Within its attributes
block, a value has the wrong data type.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: label must be a string" error
The label
below is being parsed as a Boolean, but it should be a string.
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
- type: textarea
attributes:
label: Bug Description
- type: textarea
attributes:
label: true
The error can be fixed by supplying a string value for label
. If you want to use a label
value that may be parsed as a Boolean, integer, or decimal, you should wrap the value in quotes. For example, "true"
or "1.3"
instead of true
or 1.3
.
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
- type: textarea
attributes:
label: Bug Description
- type: textarea
attributes:
label: Environment Details
Empty strings, or strings consisting of only whitespaces, are not permissible when an attribute expects a string. For example, ""
or " "
are not allowed.
If the attribute is required, the value must be a non-empty string. If the field is not required, you should delete the key-value pair.
body:
- type: input
attributes:
label: "Name"
Body[i]: id
can only contain numbers, letters, -, _
id
attributes can only contain alphanumeric characters, -
, and _
. Your template may include non-permitted characters, such as whitespace, in an id
.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: id
can only contain numbers, letters, -, _" error
name: "Bug report"
body:
- type: input
id: first name
attributes:
label: First name
The error can be fixed by ensuring that whitespaces and other non-permitted characters are removed from id
values.
name: "Bug report"
body:
- type: input
id: first-name
attributes:
label: First name
Body[i]: x
is not a permitted key
An unexpected key, x
, was provided at the same indentation level as type
and attributes
.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: x
is not a permitted key" error
body:
- type: markdown
x: woof
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
The error can be fixed by removing extra keys and only using type
, attributes
, and id
.
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug! If you need real-time help, join us on Discord."
Body[i]: label
contains forbidden word
To minimize the risk of private information and credentials being posted publicly in GitHub Issues, some words commonly used by attackers are not permitted in the label
of input or textarea elements.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: label
contains forbidden word" error
body:
- type: markdown
attributes:
value: Hello world!
- type: input
attributes:
label: Password
The error can be fixed by removing terms like "password" from any label
fields.
body:
- type: markdown
attributes:
value: Hello world!
- type: input
attributes:
label: Username
Body[i]: x
is not a permitted attribute
An invalid key has been supplied in an attributes
block.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: x
is not a permitted attribute" error
body:
- type: markdown
attributes:
x: "a random key!"
value: "Thanks for taking the time to fill out this bug!"
The error can be fixed by removing extra keys and only using permitted attributes.
body:
- type: markdown
attributes:
value: "Thanks for taking the time to fill out this bug!"
Body[i]: options
must be unique
For checkboxes and dropdown input types, the choices defined in the options
array must be unique.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: options
must be unique" error
body:
- type: dropdown
attributes:
label: Favorite dessert
options:
- ice cream
- ice cream
- pie
The error can be fixed by ensuring that no duplicate choices exist in the options
array.
body:
- type: dropdown
attributes:
label: Favorite dessert
options:
- ice cream
- pie
Body[i]: options
must not include the reserved word, none
"None" is a reserved word in an options
set because it is used to indicate non-choice when a dropdown
is not required.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: options
must not include the reserved word, none" error
body:
- type: dropdown
attributes:
label: What types of pie do you like?
options:
- Steak & Ale
- Chicken & Leek
- None
validations:
required: true
The error can be fixed by removing "None" as an option. If you want a contributor to be able to indicate that they like none of those types of pies, you can additionally remove the required
validation.
body:
- type: dropdown
attributes:
label: What types of pie do you like?
options:
- Steak & Ale
- Chicken & Leek
In this example, "None" will be auto-populated as a selectable option.
Body[i]: options
must not include booleans. Please wrap values such as 'yes', and 'true' in quotes
There are a number of English words that become processed into Boolean values by the YAML parser unless they are wrapped in quotes. For dropdown options
, all items must be strings rather than Booleans.
Errors with body
will be prefixed with body[i]
where i
represents the index of the body block containing the error. For example, body[0]
tells us that the error has been caused by the first block in the body
list.
Example of "body[i]: options
must not include booleans. Please wrap values such as 'yes', and 'true' in quotes" error
body:
- type: dropdown
attributes:
label: Do you like pie?
options:
- Yes
- No
- Maybe
The error can be fixed by wrapping each offending option in quotes, to prevent them from being processed as Boolean values.
body:
- type: dropdown
attributes:
label: Do you like pie?
options:
- "Yes"
- "No"
- Maybe
Body cannot be empty
The template body key:value
pair cannot be empty. For more information about which top-level keys are required, see "Syntax for issue forms."
The error can be fixed by adding the body:
section.
Example of "body cannot be empty" error
name: Support Request
description: Something went wrong and you need help?
---
body:
- type: textarea
attributes:
label: "What's wrong?"
In this example, the error can be fixed by deleting the ---
(document separator) between the headers and the body
section.
name: Support Request
description: Something went wrong and you need help?
body:
- type: textarea
attributes:
label: "What's wrong?"