Troubleshooting Guide - SH All-In-One Helpdesk

Solutions to common issues and problems.

Table of Contents

1. Installation Issues
2. Configuration Issues
3. Ticket Issues
4. Email Issues
5. SLA Issues
6. Portal Issues
7. Performance Issues
8. Integration Issues
9. Error Messages
10. Getting Help

Installation Issues

Module Not Found in Apps List

Symptoms:
- Module doesn't appear when searching in Apps
- "Module not found" error

Solutions:

1. Verify module location:
   bash ls -la /path/to/addons/sh_all_in_one_helpdesk/ # Should see __manifest__.py

2. Check addons path in odoo.conf:
   ini addons_path = /usr/lib/python3/dist-packages/odoo/addons,/your/custom/addons

3. Update apps list:

4. Enable developer mode

5. Apps → Update Apps List

6. Restart Odoo:
   bash sudo systemctl restart odoo

Dependency Error: html2text

Symptoms:

ModuleNotFoundError: No module named 'html2text'

Solution:
This error should not occur in the current version. The module includes a bundled lib/html2text.py. If you see this:

1. Verify the lib folder exists:
   bash ls sh_all_in_one_helpdesk/lib/ # Should show: __init__.py, html2text.py

2. Check import in mail_compose.py:
   python # Should be: from ..lib.html2text import html2text # NOT: import html2text

Missing Module Dependencies

Symptoms:

Module X is not installed

Solution:
Install required dependencies first:

Apps → Search for: mail, portal, sale_management, purchase, account, hr_timesheet, project, crm
→ Install each one

Database Constraint Errors

Symptoms:

IntegrityError: duplicate key value violates unique constraint

Solution:
1. Check for conflicting data
2. Try upgrading instead of reinstalling:
bash ./odoo-bin -d database -u sh_all_in_one_helpdesk --stop-after-init

Configuration Issues

Default Team/User Not Working

Symptoms:
- New tickets not auto-assigned
- Default team blank on tickets

Solutions:

1. Verify settings saved:
2. Helpdesk → Configuration → Settings
3. Check Default Team and Default User are set

4. Click Save

5. Check company context:

6. Ensure settings are for correct company
7. Multi-company: each company needs own settings

Stages Not Showing

Symptoms:
- Stage dropdown empty
- Kanban columns missing

Solutions:

1. Check stages exist:
2. Helpdesk → Configuration → Stages

3. Should have at least: New, In Progress, Done

4. Check sequence numbers:

5. Stages with sequence 0 may not display correctly

6. Ensure unique, positive sequence numbers

7. Create default stages:

8. If missing, create manually or reinstall module

Categories Not Visible

Symptoms:
- Category field not showing on ticket form

Solution:
Enable in settings:
- Helpdesk → Configuration → Settings
- Check "Enable Category"
- Save

Ticket Issues

Cannot Create Tickets

Symptoms:
- Create button doesn't work
- Error on save

Solutions:

1. Check required fields:
2. Partner (Customer) is required

3. Subject is required

4. Verify permissions:

5. User must have Support User role or higher

6. Settings → Users → [user] → Helpdesk section

7. Check team exists:

8. At least one team must be configured

Tickets Not Visible

Symptoms:
- User cannot see tickets
- "No records found"

Solutions:

1. Check user role:
2. Support User: sees own tickets only
3. Team Leader: sees team tickets

4. Manager: sees all tickets

5. Check team membership:

6. User must be team member or team head

7. Helpdesk → Configuration → Teams

8. Check filters:

9. Clear all filters
10. Remove search terms

Stage Transition Blocked

Symptoms:
- Cannot move ticket to certain stage
- "Access Denied" on stage change

Solution:
Check stage group restrictions:
1. Helpdesk → Configuration → Stages
2. Edit the target stage
3. Check "Group Access" field
4. Add user's group or remove restriction

Ticket Number Not Generated

Symptoms:
- Tickets have blank names
- Names show "New" instead of sequence

Solution:
Check sequence configuration:
1. Settings → Technical → Sequences
2. Find "helpdesk.ticket.sequence"
3. Verify it exists and has correct prefix

If missing, create:

<record id="helpdesk_ticket_sequence" model="ir.sequence">
    <field name="name">Helpdesk Ticket</field>
    <field name="code">helpdesk.ticket.sequence</field>
    <field name="prefix">HD</field>
    <field name="padding">5</field>
</record>

Email Issues

Emails Not Sending

Symptoms:
- No email notifications
- Stage change emails not received

Solutions:

1. Check outgoing mail server:
2. Settings → Technical → Outgoing Mail Servers

3. Test connection

4. Check email templates linked:

5. Helpdesk → Configuration → Stages

6. Edit stage → verify Email Templates field

7. Check recipient email:

8. Customer must have valid email

9. User must have valid email

10. Check mail queue:

11. Settings → Technical → Emails → Emails
12. Look for failed emails

Customer Not Receiving Updates

Symptoms:
- Customer doesn't get notifications
- Only agent gets emails

Solutions:

1. Check follower status:
2. Open ticket
3. Verify customer is a follower

4. Or enable "Auto Add Customer as Follower" in settings

5. Check message type:

6. Use "Send Message" not "Log Note"

7. Notes are internal only

8. Verify customer email:

9. Open customer contact
10. Ensure email is set

Email Template Variables Not Working

Symptoms:
- Email shows ${object.name} literally
- Variables not replaced

Solution:
Check template syntax:

<!-- Correct Qweb syntax -->
<t t-out="object.name"/>

<!-- Or Jinja-style (older) -->
${object.name}

SLA Issues

SLA Not Calculating

Symptoms:
- No SLA deadline on tickets
- SLA status blank

Solutions:

1. Verify SLA policy exists:
2. Helpdesk → Configuration → SLA Policies

3. Create policy for team

4. Check policy matches ticket:

5. Policy team = ticket team

6. Policy ticket type = ticket type (or blank for all)

7. Verify working hours:

8. Team must have working hours calendar
9. Helpdesk → Configuration → Teams → edit team

SLA Deadline Wrong

Symptoms:
- Deadline seems off
- Not accounting for weekends

Solutions:

1. Check working calendar:
2. Verify team's working hours calendar

3. Check calendar has correct days/hours

4. Check timezone:

5. User timezone setting
6. Server timezone

7. Calendar timezone

8. Review SLA time settings:

9. Days + Hours + Minutes all contribute
10. 1 day = 1 working day, not 24 hours

SLA Status Not Updating

Symptoms:
- SLA shows wrong status
- Status doesn't change when stage changes

Solution:
Manually trigger update:

# In Odoo shell or via action
ticket.change_sh_status()

Or check the write method is triggering status update.

Portal Issues

Customer Can't Access Portal

Symptoms:
- Login fails for customer
- No portal access

Solutions:

1. Grant portal access:
2. Contacts → select customer
3. Action → Grant Portal Access

4. Enter email

5. Check portal user group:

6. User should have "Portal" group

7. Not internal user group

8. Verify email sent:

9. Check email queue
10. Customer needs activation email

Customer Sees Wrong Tickets

Symptoms:
- Customer sees other customers' tickets
- Tickets missing from portal

Solutions:

1. Check portal user level:
2. User's Helpdesk portal access level

3. Settings → Users → [user] → Helpdesk section

4. Verify partner matching:

5. Ticket partner_id must match portal user's partner_id

Portal Attachments Fail

Symptoms:
- Cannot upload files
- "File too large" error

Solution:
Increase file size limit:
- Helpdesk → Configuration → Settings
- Increase "Portal File Size Limit"

Performance Issues

Slow Ticket List Loading

Symptoms:
- Ticket list takes long to load
- Timeout errors

Solutions:

1. Reduce visible fields:
2. Remove computed fields from list view

3. Use summary views

4. Add database indexes:
   sql CREATE INDEX idx_ticket_stage ON helpdesk_ticket(stage_id); CREATE INDEX idx_ticket_user ON helpdesk_ticket(user_id);

5. Archive old tickets:

6. Set tickets to inactive after closure
7. Use auto-close feature

Dashboard Slow

Symptoms:
- Dashboard takes long to render
- Counters don't update

Solutions:

1. Reduce dashboard stages:
2. Only show essential stages in dashboard

3. Company settings → Dashboard Filter/Table stages

4. Limit date range:

5. Use shorter default period
6. Monthly instead of yearly

Search Performance

Symptoms:
- Search takes too long
- Timeouts on search

Solutions:

1. Use specific filters:
2. Avoid wildcard searches

3. Filter by date range first

4. Index frequently searched fields:
   sql CREATE INDEX idx_ticket_subject ON helpdesk_ticket USING gin(to_tsvector('english', ticket_subject));

Integration Issues

Sales Order Integration Not Working

Symptoms:
- No "Create Ticket" button on SO
- Ticket not linking to SO

Solutions:

1. Verify sub-module loaded:
2. Check sh_helpdesk_so folder exists

3. Module should auto-load with main module

4. Check sale_management installed:

5. Apps → Sales
6. Must be installed

Timesheet Not Recording

Symptoms:
- Timer starts but no entry created
- Hours not appearing

Solutions:

1. Check project configuration:
2. Company settings → Default Project

3. Must have valid project

4. Verify employee link:

5. User must have employee record

6. HR → Employees

7. Check timesheet module:

8. hr_timesheet must be installed

CRM Link Missing

Symptoms:
- No "Create Lead" button
- Lead count not showing

Solution:
Verify CRM installed:
- Apps → CRM
- Install if missing

Error Messages

"Access Denied"

Cause: User lacks permission

Solution:
- Check user's helpdesk group
- Verify record rules for user's role
- Ensure user is in correct team

"Constraint Error"

Cause: Data validation failed

Solution:
- Check required fields
- Verify unique constraints
- Check related records exist

"KeyError: 'field_name'"

Cause: Code references non-existent field

Solution:
- Upgrade module to get latest fields
- Check for customization conflicts

"RecursionError"

Cause: Infinite loop in computed fields

Solution:
- Check custom computed fields
- Review depends decorators
- Look for circular references

"TransactionRollbackError"

Cause: Database conflict

Solution:
- Retry the operation
- Check for concurrent edits
- Review database locks

Diagnostic Commands

Check Module Status

# Odoo shell
env['ir.module.module'].search([('name', '=', 'sh_all_in_one_helpdesk')]).state

List Installed Modules

./odoo-bin shell -d database
>>> env['ir.module.module'].search([('state', '=', 'installed')]).mapped('name')

Check Ticket Count

>>> env['helpdesk.ticket'].search_count([])

View Error Logs

# Linux
tail -f /var/log/odoo/odoo.log | grep -i error

# Docker
docker logs -f container_name 2>&1 | grep -i error

Test Email

>>> env['mail.mail'].create({
...     'subject': 'Test',
...     'body_html': 'Test email',
...     'email_to': '[email protected]'
... }).send()

Getting Help

Before Asking for Help

Gather this information:

diagnostic_info:
  odoo_version: "18.0"
  module_version: "18.0.0.0"
  python_version: "3.x.x"
  database_type: "PostgreSQL x.x"
  deployment: "Docker / Native / Hosted"
  error_message: "Full error text"
  steps_to_reproduce: "1. Go to... 2. Click..."
  expected_behavior: "What should happen"
  actual_behavior: "What actually happens"

Support Channels

1. Documentation: Review this guide
2. Odoo Forums: community.odoo.com
3. GitHub Issues: Report bugs
4. Original Author: Softhealer Technologies

Reporting Bugs

Include:
- Odoo version
- Module version
- Full error traceback
- Steps to reproduce
- Screenshots if applicable

Troubleshooting Checklist

general_troubleshooting:
  - id: TS-001
    check: "Odoo service running"
    command: "systemctl status odoo"
    status: pending

  - id: TS-002
    check: "Database accessible"
    command: "psql -U odoo -d database -c 'SELECT 1'"
    status: pending

  - id: TS-003
    check: "Module installed"
    location: "Apps → search 'helpdesk'"
    status: pending

  - id: TS-004
    check: "User has permissions"
    location: "Settings → Users → Helpdesk section"
    status: pending

  - id: TS-005
    check: "Email server configured"
    location: "Settings → Technical → Outgoing Mail"
    status: pending

  - id: TS-006
    check: "At least one team exists"
    location: "Helpdesk → Configuration → Teams"
    status: pending

  - id: TS-007
    check: "Stages configured"
    location: "Helpdesk → Configuration → Stages"
    status: pending

  - id: TS-008
    check: "Company settings complete"
    location: "Helpdesk → Configuration → Settings"
    status: pending

Next: CHECKLISTS.md