Troubleshooting Guide¶

Version: Arctyk ITSM v0.6.0+
Last Updated: January 2026

Web server does not load website¶

This can happen for a number or reasons. The most common reason is that the code base has error or errors and is preventing the website from being served.

1. Check Docker logs for errors:

   docker compose logs -f
   

2. Correct any errors you find.

3. Stop the container: docker compose down
4. Rebuild and restart the container: docker compose up -d --build

To stop or exit Docker logs, use CTRL + C

Common Linting Errors¶

Python/Django Linting (Pylance, Black, isort)¶

Expected 2 blank lines¶

Error:

expected 2 blank lines, found 1

Explanation: PEP 8 requires two blank lines before top-level functions and classes.

Solution:

# Bad
def first_function():
    pass

def second_function():  # ❌ Only 1 blank line
    pass

# Good
def first_function():
    pass


def second_function():  # ✅ 2 blank lines
    pass

Line too long¶

Error:

line too long (92 > 88 characters)

Explanation: Black enforces an 88-character line limit (configured in pyproject.toml).

Solution:

# Bad
very_long_variable_name = some_function_call(parameter1, parameter2, parameter3, parameter4)

# Good
very_long_variable_name = some_function_call(
    parameter1, parameter2, parameter3, parameter4
)

Import not at top of file¶

Error:

Import "X" could not be resolved / Import should be placed at the top of the module

Explanation: Imports should be at the top of the file, organized by stdlib → third-party → local.

Solution:

# Bad
def my_function():
    import datetime  # ❌

# Good
import datetime  # ✅

def my_function():
    pass

Auto-fix: Run isort to automatically organize imports:

isort src/

Unused import¶

Error:

"X" imported but unused

Solution: Remove the unused import or use it. Common false positives in Django:

# Models that are imported for relationship purposes
from .models import Ticket  # noqa: F401  # Imported for FK relationships

Missing migrations¶

Error:

You have 3 unapplied migration(s). Your project may not work properly until you apply the migrations

Solution:

docker compose exec web python src/manage.py migrate

Template Linting (djLint)¶

Expected whitespace in template tags¶

Error:

Expected whitespace after "{%" or before "%}"

Explanation: Template tags should have spaces inside the delimiters.

Solution:

{# Bad #}
{%if condition%}  ❌
{%endif%}

{# Good #}
{% if condition %}  ✅
{% endif %}

Unclosed template tags¶

Error:

Unclosed tag on line X. Expected {% endblock %}.

Solution: Ensure all Django template tags are properly closed:

{% block content %}
    ...
{% endblock %}  {# Must close every block #}

Invalid template variable¶

Error:

Template variable "X" could not be resolved

Explanation: Variable doesn't exist in the template context.

Solution:

• Check view context passes the variable
• Use {{ variable|default:"fallback" }} for optional variables
• Verify variable name spelling

JavaScript/Node Linting (ESLint, Prettier)¶

Unexpected trailing comma¶

Error:

Unexpected trailing comma

Explanation: Prettier may add/remove trailing commas based on configuration.

Solution: Let Prettier auto-format:

npm run format

Or configure in .prettierrc:

{
    "trailingComma": "es5"
}

'X' is defined but never used¶

Error:

'myVariable' is defined but never used (no-unused-vars)

Solution: Remove unused variables or prefix with underscore if intentionally unused:

// If truly unused
const _unusedVar = 123; // ESLint will ignore

CSS/SCSS Linting¶

Unknown at rule¶

Error:

Unknown at rule @import (scss)

Explanation: Using SCSS syntax in a file treated as CSS.

Solution: Ensure file has .scss extension and SCSS processor is configured.

Auto-fixing Linting Issues¶

Python:

# Format with Black
black src/

# Sort imports with isort
isort src/

# Both together (recommended)
black src/ && isort src/

Templates:

# Format Django templates with djLint
djlint src/*/templates --reformat

JavaScript:

# Format with Prettier
npm run format

# Or auto-fix ESLint issues
npm run lint:fix

Disabling Linting Rules¶

When absolutely necessary (use sparingly):

Python:

# Single line
result = long_function_call()  # noqa: E501

# Entire file
# flake8: noqa

# Specific rule for block
# pylint: disable=line-too-long
code_here()
# pylint: enable=line-too-long

Django Templates:

{# djlint:off #}
<div>Unformatted HTML</div>
{# djlint:on #}

JavaScript:

// Single line
// eslint-disable-next-line no-console
console.log("Debug message");

// Entire file
/* eslint-disable */

Only disable linting rules when you have a legitimate reason. Document why the rule is disabled with a comment.