Troubleshooting¶
This guide covers common issues and their solutions.
Installation Issues¶
Module Not Appearing in Apps List¶
Symptoms:
Cannot find “Atlas Construction” in Apps menu
Module doesn’t appear after clicking “Update Apps List”
Solutions:
Verify module is in addons path:
ls -la /path/to/odoo/addons/atlas_construction
Check Odoo configuration:
grep addons_path /etc/odoo/odoo.conf
Restart Odoo server:
sudo systemctl restart odoo
Update apps list with developer mode:
Settings → Activate Developer Mode
Apps → Update Apps List
Check server logs for errors:
tail -f /var/log/odoo/odoo.log
Dependency Installation Fails¶
Error: “Could not install module: Missing dependency”
Solution:
Install missing dependencies first
Navigate to Apps
Search for required module (project, sale, purchase, account)
Install it
Try installing atlas_construction again
Permissions & Security¶
Cannot Edit Budget Lines¶
Most Common Issue!
Symptoms:
Budget lines appear as read-only text
Cannot click fields to edit
No “+” button to add lines
Changes don’t save
Causes:
User lacks Job Cost Manager security group
Browser cache issues
User viewing wrong company’s projects
Solutions:
Check Security Groups (Primary solution):
Settings → Users & Companies → Users
Select the user
Find “Job Costing” section
Verify role is “Manager” (NOT “User”)
If wrong, change to Manager and click Save
User must log out and log back in
Clear Browser Cache:
Press Ctrl+Shift+Delete (or Cmd+Shift+Delete on Mac)
Clear cached images and files
Close browser completely
Reopen and log in again
Check Company Access:
Settings → Users & Companies → Users
Select user
Verify “Allowed Companies” includes project’s company
Add if missing
Verify Record Rules:
Settings → Technical → Security → Record Rules
Search for “job_cost_line”
Check if custom rules are blocking access
Important
The most common cause is missing the Job Cost Manager security group. Always check this first! See Security & Permissions for detailed permission information.
Cannot Approve Change Orders¶
Symptoms:
“Approve” button is missing or grayed out
User can view but not modify change orders
Solution:
Assign Change Order Manager security group:
Settings → Users → Select user
Find “Change Orders” section
Change role to “Manager”
User logs out/in
Cannot Create Invoices from Milestones¶
Symptoms:
“Create Invoice” button missing
Milestone shows “Ready” but cannot bill
Solution:
Assign Billing Manager security group:
Settings → Users → Select user
Find “Progress Billing” section
Change role to “Manager”
Can Only See Some Projects¶
Symptoms:
User cannot see all company projects
Projects disappear from list
Causes:
User has “User” level permissions (sees only followed projects)
User in wrong company
Solutions:
Upgrade to Manager role (see all company projects)
Or add as follower to specific projects:
Open project form
Click followers icon (top right)
Add user
Cost Tracking Issues¶
Committed Cost Not Updating¶
Symptoms:
Created PO linked to job cost line
Committed cost shows $0
Causes:
PO still in draft state
PO line not linked to job cost line
PO cancelled
Solutions:
Confirm the PO:
Open purchase order
Click “Confirm Order” button
Check PO state changes to “Purchase Order”
Committed cost updates immediately
Verify PO Line Linkage:
Open PO
Check each line has:
Project field filled
Job Cost Line field filled
Edit and add if missing
Check PO State:
Only confirmed POs (state = purchase/done) affect committed cost
Draft and cancelled POs do not count
Actual Cost Not Matching Bills¶
Symptoms:
Posted vendor bills
Actual cost on budget line doesn’t update
Causes:
Bill line not linked to job cost line
Bill still in draft
Wrong job cost line selected
Solutions:
Check Bill Line Fields:
Open vendor bill
For each line verify:
Project field: Select construction project
Job Cost Line field: Select specific budget line
Save bill
Post the Bill:
Bills in draft state don’t affect actual cost
Click “Post” to confirm
Actual cost updates immediately
Verify Correct Line:
Ensure bill linked to correct job cost line
Phase and category must match your intent
Warning
Just setting the Project field is NOT enough! You must also set the Job Cost Line field for costs to track properly.
Variance Calculations Wrong¶
Symptoms:
Variance doesn’t match manual calculation
Totals seem off
Checks:
Understand the Formula:
Variance = Budget - (Actual + Committed)
Verify Components:
Budget: Is it correct?
Actual: Includes all posted bills?
Committed: Includes all confirmed POs?
Remember:
Negative variance = over budget
Positive variance = under budget
Solutions:
Recompute Fields:
Construction → Job Costing → Budget Lines
Find affected line
Action → Recompute
Forces recalculation
Check Dependencies:
Are POs properly confirmed?
Are bills properly posted?
Are lines linked correctly?
Workflow Problems¶
Budget Template Not Applying¶
Symptoms:
“Generate Budget from Template” button missing
Template applies but creates no lines
Wrong amounts in generated lines
Solutions:
Button Not Visible:
Button only shows when project has ZERO budget lines
Delete existing lines first if you want to reapply
Or add lines manually
No Lines Created:
Open the template
Verify it has template lines defined
Check percentages add up properly
Verify phases and categories exist
Wrong Amounts:
Template uses percentages of total budget
Check “Total Budget” entered in wizard
Verify template line percentages
Recalculate: (Total Budget × Percentage)
Change Orders Not Updating Budget¶
Symptoms:
Approved change order
Project budget not updated
Causes:
Change order not fully approved
Budget update failed (check logs)
Missing permissions
Solutions:
Check CO State:
Open change order
Verify state is “Approved” (not just “Submitted”)
If stuck, check approval permissions
Review Logs:
tail -f /var/log/odoo/odoo.log | grep -i "change order"
Look for errors during budget update
Note any missing fields or validation failures
Manual Budget Update:
Navigate to project Job Costing tab
Manually add budget lines from CO
Or click “Add Budget Line” for each CO line
Daily Logs Not Saving¶
Symptoms:
Daily log form closes without saving
Data disappears after save
Causes:
Required fields missing
Date validation failures
Permission issues
Solutions:
Fill Required Fields:
Date (required)
Project (required)
Weather conditions
Temperature
Check Date:
Date must be valid
Cannot be in future (if configured)
Cannot duplicate existing log (if configured)
Verify Permissions:
User needs Daily Log User or Manager role
Can only edit own logs (unless Manager)
Performance Issues¶
Slow Project Form Loading¶
Symptoms:
Project form takes >5 seconds to load
Budget tab slow to display
Page freezes when opening
Causes:
Too many budget lines (>200)
Complex computed fields
Large number of POs/bills linked
Solutions:
Optimize Budget Lines:
Consolidate similar lines
Archive completed projects
Use appropriate detail level (25-50 lines typical)
Database Optimization:
-- Reindex tables REINDEX TABLE atlas_job_cost_line; REINDEX TABLE purchase_order_line; REINDEX TABLE account_move_line; -- Analyze for query optimization ANALYZE atlas_job_cost_line;
Server Resources:
Check server CPU/memory usage
Increase workers in odoo.conf
Add database connection pooling
Reports Taking Too Long¶
Symptoms:
Job cost reports timeout
Variance analysis won’t load
Solutions:
Narrow Date Range:
Don’t query all historical data at once
Use date filters
Limit Projects:
Run reports for specific projects
Don’t select “All Projects”
Schedule Reports:
Use Odoo’s scheduled actions
Generate reports overnight
Email results
Data Issues¶
Duplicate Budget Lines¶
Symptoms:
Same phase/category appears twice
Totals counting double
Causes:
Manual creation after template
Template applied twice
Data import errors
Solutions:
Identify Duplicates:
Construction → Job Costing → Budget Lines
Filter by project
Sort by phase, then category
Look for duplicates
Merge or Delete:
Keep line with correct data
Delete duplicate
Or combine amounts and delete one
Prevent Future:
Train users on proper workflow
Delete all lines before reapplying template
Missing Phases or Categories¶
Symptoms:
Cannot create budget line
Phase/Category dropdown empty
“Field required” error
Solutions:
Create Missing Items:
Construction → Configuration → Phases
Or Construction → Configuration → Cost Categories
Click Create
Add missing item
Check Company:
Phases/categories might be for different company
Create new or assign to correct company
Data Migration Issues¶
Symptoms:
Imported data not showing
Fields not mapping correctly
Solutions:
Use Import Template:
Export existing line as template
Match column headers exactly
Fill in required fields
Required Fields for Budget Lines:
Project (database ID or name)
Phase (database ID or name)
Category (database ID or name)
Budget Amount (number)
Check Error Log:
Click on import error
Read error message carefully
Fix data and retry
Integration Problems¶
Purchase Orders Not Linking¶
Symptoms:
Cannot select job cost line in PO
Field not visible
Causes:
Purchase module customization
View not updated
Missing field
Solutions:
Verify View:
Settings → Technical → User Interface → Views
Search for “purchase.order.line.form”
Check atlas_construction view is active
Update View:
Apps → Atlas Construction
Click “Upgrade”
Reload page
Timesheet Integration Not Working¶
Symptoms:
Timesheet hours not updating actual cost
Labor costs not tracking
Solutions:
Enable Integration:
Construction → Configuration → Settings
Enable “Timesheet Integration”
Set labor rate calculation method
Configure Rates:
HR → Employees
Set employee cost rate
Or use company default
Link Timesheets:
Timesheets must have:
Project filled
Optionally: Job cost line
Browser / UI Issues¶
Form Fields Not Saving¶
Symptoms:
Type in field, value disappears
Cannot modify certain fields
Solutions:
Check Field Readonly:
Some fields computed (cannot edit)
Some fields state-dependent
Verify Not Archived:
Record might be archived
Check active filter
Database Lock:
Another user editing same record
Wait or refresh
Mobile Access Issues¶
Symptoms:
Forms too wide for mobile
Buttons too small to click
Solutions:
Use Odoo Mobile App:
Better mobile experience
Download from app store
Responsive View:
Odoo automatically adapts
Rotate to landscape
Pinch to zoom
Simplified Forms:
Use list views instead of forms
Use kanban views for better mobile UX
Getting More Help¶
Check Documentation¶
Before contacting support:
Read relevant documentation sections
Check this troubleshooting guide
Review Security & Permissions for permission issues
Consult workflow documentation
Enable Debug Mode¶
For better error messages:
Settings → Activate Developer Mode
Reproduce the issue
Note any error messages or tracebacks
Take screenshots
Check Server Logs¶
# View real-time logs
tail -f /var/log/odoo/odoo.log
# Search for errors
grep -i error /var/log/odoo/odoo.log
# Search for specific module
grep -i atlas_construction /var/log/odoo/odoo.log
Contact Support¶
When reporting issues, include:
System Information:
Odoo version
Module version
Operating system
Browser and version
Description:
What you were trying to do
What happened instead
Steps to reproduce
Evidence:
Screenshots
Error messages
Server logs (relevant excerpts)
Database backup (if data issue)
Troubleshooting Done:
Steps already tried
Results of each attempt
Community Resources¶
Odoo Documentation: https://www.odoo.com/documentation/
Odoo Forums: https://www.odoo.com/forum/
GitHub Issues: (if open source)
—
Last Updated: 2025-10-31
If your issue isn’t covered here, please report it so we can improve this guide!