# Troubleshooting

## Quick checklist

{% hint style="warning" %}
When something "doesn't work", start with these quick questions:

* Is the field **created** as type *Time Tracking* or *Duration* (not text/number)?
* Is the field **added to the right screens** (create, view, edit, transition, portal)?
* Is the field **configured for this project / issue type** (field context)?
* Do you have the **right permissions** to edit this issue?
* Has at least one issue been saved with a value in this field (for JQL/dashboards)?
  {% endhint %}

If all of those look correct and the problem persists, use the sections below.

***

## Field and display issues

<details>

<summary>Field is not visible on issues</summary>

**Symptoms**

* You created a Time tracking field, but it does not show on the issue view.
* Users report "the field is missing" on certain projects or issue types.

**Checks**

* Confirm the field exists and its type is **Time Tracking** or **Duration**.
* Check that it is **added to screens**:
  * Create Issue screen
  * Edit / View Issue screen
  * Transition screens (if you expect it there)
* Check the field's **context**:
  * Make sure the field is configured for this project and issue type.
* For team-managed projects, check the **Issue layout** inside project settings.

If the field appears in some projects but not others, it's almost always a screen or context configuration issue, not a bug in the app.

</details>

<details>

<summary>Field is visible but cannot be edited</summary>

**Symptoms**

* You see the Time tracking field, but there is no edit option.
* Inline edit is disabled, or clicking does nothing.

**Checks**

* Verify you have permission to **edit issues** in that project.
* Check whether the field is on a **read-only screen** or shown only in a read-only panel.
* On workflow transitions, verify that the field is actually present on the **transition screen**, not just on the view screen.

If some users can edit and others cannot, the root cause is almost always **project permissions**, not the field type itself.

</details>

<details>

<summary>Field values look "wrong" or confusing</summary>

**Symptoms**

* The field shows `0m` when you expected a value.
* The field displays raw seconds with "s" instead of `w/d/h/m`.
* The "total" seems inconsistent with original + logged.

**Possible reasons**

* The field has never been set on this issue — default display is `0m` or empty.
* The admin enabled an **"export as seconds"** mode, so values are shown like `3600s` instead of `1h`.
* Working time assumptions changed (hours per day / days per week), affecting how existing seconds are formatted.

**What to do**

* Confirm with your admin:
  * Current `hours per day` and `days per week` configuration.
  * Whether the field is configured to **export/format** as seconds.
* If the same issue shows different values for different people, ask for screenshots and check:
  * are you actually looking at the same field?
  * are any browser plugins modifying the UI?

</details>

***

## Validation errors

<details>

<summary>"Duration values must be non-negative when provided"</summary>

**Symptoms**

* On saving or updating the issue, you see the error: `Duration values must be non-negative when provided.`
* The change is not saved.

**What it means**

The field has a built-in validation rule that refuses to save if any of these are negative:

* Original estimate (seconds)
* Time spent (seconds)
* Remaining estimate (seconds)

**What to check**

* Make sure you are not entering durations with a minus sign (for example `-1h`).
* If you are using a "log work" style editor:
  * Check if you accidentally logged a negative duration.
  * Check if manually editing remaining time caused it to go below zero.

If the field shows negative values without you entering a minus sign, capture:

* project key,
* issue key,
* field name,
* what you did just before the error,

and pass this to your admin or the app vendor so they can review the scenario.

</details>

<details>

<summary>"Duration value must be non-negative" (Duration field)</summary>

**Symptoms**

* On saving or updating an issue, you see the error: `Duration value must be non-negative.`
* The change is not saved.

**What it means**

The Duration field has a validation rule that refuses to save if the duration value is negative.

**What to check**

* Make sure you are not entering durations with a minus sign (for example `-1h`).
* If you are setting the value via REST API, ensure `durationSeconds` is `>= 0`.

</details>

<details>

<summary>"Invalid duration" or similar validation messages</summary>

**Symptoms**

* You see an inline error like "Invalid duration format" or "Please enter duration in the correct format".
* You cannot save until you change the value.

**Typical causes**

* Typo in the value (for example `2d 90x`, `1h 60`, or missing unit).
* Unsupported format (for example "2 hours" instead of `2h`).
* Mixing up decimal numbers and units in a way the parser does not support.

**How to fix**

* Use standard Jira-style duration syntax:
  * `30m`, `2h`, `1d 3h`, `2w 1d`, `1d 4h 30m`
* If you enter just a number (for example `120`), check with your admin how plain numbers are interpreted (minutes vs hours).

If a specific value *should* be valid but is rejected, capture the exact string you entered and share it with the admin/vendor.

</details>

***

## JQL and search issues

<details>

<summary>JQL: field or aliases "not found"</summary>

**Symptoms**

* JQL errors like "The field 'XYZ' does not exist".
* Autocomplete does not show your time tracking field or any of its aliases.

**Checks**

* Use the **exact display name** of the field in quotes, then alias suffix, for example: `"QA Estimate".RemainingEstimateSeconds` (Time Tracking) or `"SLA Limit".DurationSeconds` (Duration)
* Make sure at least **one issue** has been saved with a value in this field.
  * Sometimes fields appear in autocomplete only after they hold data.
* Confirm you are in the correct Jira product (Software, Service Management) and working with the right project.

If autocomplete still doesn't show your field:

* Ask a Jira admin to confirm:
  * the field exists,
  * it is truly type **Time Tracking** or **Duration**,
  * it is associated with this project and issue type.

</details>

<details>

<summary>JQL: query runs but returns 0 issues</summary>

**Symptoms**

* JQL is valid (no error), but returns no results even though issues clearly have values.

**Common causes**

* Comparing against seconds with the **wrong threshold** (for example using `> 14400` while your estimates are in minutes and never reach that number).
* Using the wrong alias (for example `OriginalEstimate` instead of `OriginalEstimateSeconds` when you intended numeric comparison).
* The field is populated only on some projects or issue types, but your filter spans all projects.

**What to try**

* Start with a very broad condition, for example: `"QA Estimate".OriginalEstimateSeconds > 0`
* Limit to a project where you know values exist: `project = ABC AND "QA Estimate".OriginalEstimateSeconds > 0`
* If string-based queries work but seconds-based ones do not, verify the thresholds and units you're assuming.

</details>

***

## Dashboards and automation

<details>

<summary>Dashboards not showing expected values</summary>

**Symptoms**

* A dashboard gadget based on a filter returns fewer issues than expected.
* The field column appears blank for some issues.

**Checks**

* Verify the underlying **filter** first:
  * Open the filter in advanced search and confirm the results are what you expect.
* Confirm the field is **on the issues** returned by the filter:
  * Open an issue that should appear; check the Time tracking field on the issue view.
* Ensure the gadget is configured to show the **field column** (for table gadgets).

If the filter is correct but the gadget is wrong, re-save the gadget configuration and check:

* selected filter,
* selected columns (for table-type gadgets),
* any grouping parameters.

</details>

<details>

<summary>Automation not triggering as expected</summary>

**Symptoms**

* An automation rule with a JQL condition using time tracking aliases never fires.
* Or it fires, but on the wrong set of issues.

**Checks**

* Test the JQL **directly** in advanced search:
  * If the JQL returns no issues, the rule will not trigger either.
* Confirm the rule's **scope** matches where your field is used (projects, issue types).
* Make sure the rule runs "on schedule" or on a relevant event, not just on a transition that never happens.

If JQL returns the correct issues but automation still fails:

* Check the rule's audit log for:
  * issues skipped because they did not match conditions,
  * errors during execution,
  * permissions problems.

</details>

***

## Portal and transition behaviours

<details>

<summary>Field not working on portals or transitions</summary>

**Symptoms**

* Time tracking appears on the portal but cannot be edited.
* The field appears on some transitions but not others.

**Checks**

* In service projects, verify the **request form** is configured to show the field and whether it is editable for customers.
* In workflows, check the **transition screens**:
  * The field must be added to each transition screen where you want it to appear.
* Some teams choose to make the field **read-only** on portals or transitions to avoid accidental edits; this may be intentional.

If you expect the field to be editable and it is not, review screen configuration and permissions with a Jira admin.

</details>

***

## When to contact support

If none of the above helps, collect a small diagnostic bundle before contacting the app vendor or your internal admin team.

{% hint style="info" %}
**What to include in your support request:**

* Site URL (cloud domain).
* Project details where the problem occurs.
* Screens from field configuration.
* JQL you were trying to run (if relevant).
* Screenshots showing the field on the issue (or its absence), the error message, and the automation rule or dashboard configuration (if involved).
* A short description of what you did, what you expected, and what actually happened.
  {% endhint %}

With this information, most problems can be isolated quickly as either configuration (screens, contexts, permissions) or a specific edge case in how values are entered and interpreted.

***

## See also

{% content-ref url="configuration" %}
[configuration](https://teranoapps.gitbook.io/time-tracking-custom-field/configuration)
{% endcontent-ref %}

{% content-ref url="search-and-reporting" %}
[search-and-reporting](https://teranoapps.gitbook.io/time-tracking-custom-field/search-and-reporting)
{% endcontent-ref %}

{% content-ref url="licensing-support-and-contact" %}
[licensing-support-and-contact](https://teranoapps.gitbook.io/time-tracking-custom-field/licensing-support-and-contact)
{% endcontent-ref %}
