How EspoCRM logs and debug mode help you find faults
When a user reports an error, a scheduled job quietly stops, or a record page crawls, the first move is to read what EspoCRM recorded, not to guess at a fix. The application logs, the SQL logging options and the debug mode are where that evidence lives, and a team running EspoCRM on its own servers needs them most after it has added custom entities, formula scripts or integrations, and after every upgrade, when a change that worked before can fail in a new way. Without this step, teams tend to restart services or edit configuration blindly, which hides the original fault and makes it harder to reproduce.
The application log records errors and warnings from the EspoCRM application itself, including failed requests and exceptions raised by custom code. Separate SQL logging can show the queries that ran, and failed-SQL logging isolates the statements the database rejected, which matters when a customized list view or report breaks after a field change. Log levels control how much detail is written, so a team should confirm which levels its installation uses, where the files sit on its server and who can read them, because these files often contain record data and identifiers. The admin interface also exposes an app log view, so an administrator can check recent entries without shell access, although the files on disk remain the complete record.
Debug mode adds detail for diagnosis, but it is not a setting to leave on. Verbose output can expose internal paths, query text and sensitive values, and it slows requests, so the sound practice is to enable it on a test copy or for a short, documented window on production, then turn it off and remove the traces. Before any change, decide who may toggle debug mode, where its output is stored, how long it is retained and who reviews it. The open-source edition is free to download and self-host, according to the EspoCRM pricing page, so the cost of this work is the engineering time and the infrastructure you already run. Confirm the exact log paths, level names and debug settings for your version in the EspoCRM server configuration documentation before you write runbooks.
Logging options and when each fits
This table compares the EspoCRM logging options you are likely to use when something breaks, the situation each suits and what it costs to leave switched on. Confirm level names, file locations and switch names for your release in the server configuration and administration documentation before you change anything. The main takeaway is that verbose options belong in short diagnostic windows, and each one needs an owner and a documented switch-off step.
| Option | Best fit | Cost of leaving it on | Confirm before use |
|---|---|---|---|
| Standard application log level | Routine monitoring and error triage after go-live | Steady disk growth; retention and rotation must be set | Level names, log directory and rotation settings for your version |
| Verbose or debug-level application logging | Reproducing one fault in a test copy or short production window | Large files, slower requests and possible personal data in entries | Which level adds SQL and stack detail in your release |
| SQL query logging | Checking which queries run during a slow list view, report or workflow | High volume, extra overhead and record values in log lines | The config key, where output is written and whether values are included |
| Failed SQL logging | Catching queries that error after custom field, layout or index changes | Usually modest volume, but error text can expose data | Whether it records the error text and bound values |
| Admin UI application log | Admins who need recent entries without shell access to the server | Exposes log content to any role that can open it, so access must be limited | Whether it reads the same file as the server log and how many lines it shows |
| Debug mode | Short-lived diagnosis of a reproducible error on a non-production copy | Detailed error output can reach users and reveal internals; it must be turned off | The setting name, whether it applies per instance and any cache rebuild step |
| Several verbose options left on in production | Not a fit; these are temporary states | Disk exhaustion, personal data in logs and degraded performance | A named owner, an expiry date and a tested switch-off step |
Which failures show up where
Most EspoCRM problems reach users as a symptom: a login that fails, a record that will not save, an inbox that stops updating. The cards below pair each symptom with the log or admin view that is most likely to explain it, so you can start from what users report instead of guessing which component failed.
Failed logins
A user who cannot sign in may be hitting a wrong password, a lockout, an identity provider mismatch or a server-side error. Start with the application log for the failed attempt and check whether the failure is a credential problem or an exception. If single sign-on is configured, confirm which login path the user took, because the OIDC fallback login and the standard form fail in different ways.
Failed saves and formula errors
When a record fails to save, the error often comes from a before-save script, a dynamic logic rule or a validation step rather than the database. Check the application log at the time of the save and note which entity and field were involved. Formula Script runs in before-save scripts, workflows and BPM, so a failure in one of those places can look like a generic save error to the user.
Background job errors
Workflows, scheduled reports and queued actions run as background jobs, so their failures do not appear in the browser. Review the scheduled job status and the application log for the job's execution window. A job that never runs and a job that runs and fails leave different traces, so confirm which one you are looking at before changing any settings.
Email fetch errors
An inbox that stops updating is usually a fetch problem, not a display problem. Look in the application log for connection, authentication or parsing errors tied to the mailbox, and confirm that the scheduled fetch is actually executing. Errors from OAuth-based mail accounts often appear after a token change, so compare the timing of the first missed fetch with any credential or policy change.
Slow list views and reports
Slow pages show up as long response times rather than errors, so the evidence sits in the SQL log. Enable SQL logging for a short, controlled window to capture the queries behind one slow list view, then identify which filters, sorts or joins drive the time. Turn logging off once you have the sample, because verbose query logs add load and can expose data.
Database errors
Database failures such as a missing column after an upgrade or a failed query on a custom field appear in the failed-SQL log with the statement that broke. Compare the failing statement with the entity metadata and recent customization changes. Confirm the database server version against the supported list before assuming the application is at fault, since version mismatches can produce errors that look like code bugs.
How to enable diagnostics without leaving traces in production
This sequence lets you capture the EspoCRM log entries for one problem, with a named owner for each change and a record of what was turned on and back off. It keeps verbose output short-lived and limits who can read it.
Confirm the log path and permissions
The administrator on the web server confirms where this EspoCRM installation writes its application log and that the web server user can write to that location. Check the path against your installation method, because a Docker-based install keeps files inside a container volume. Confirm that other local users cannot read the directory. Ask the vendor or check the server configuration docs if the location is unclear. The step is done when you can list the newest log file and see entries from a recent action, such as a failed login.
Set the log level for the investigation
Set the application log level to the lowest verbosity that will still capture the failure. Make the change in the administration area or the configuration file, and confirm the exact setting names in the server configuration docs for your version. Record the previous value in the change ticket with your name and the time. Trigger a harmless action, such as a login, to confirm the new level writes entries. The step is done when a test action produces a log line at the new level and the old value is written down.
Reproduce the issue with a test user
Use a dedicated test user with the same role, teams and portal access as the person who reported the problem. Shared administrator accounts make log entries hard to attribute, and the security docs recommend keeping admins off daily work. Repeat the exact steps, including the entity, field and action. Write down the timestamp and the record ID so you can match them to log lines. Use a test record that can be deleted later. The step is done when the problem recurs under the test user and you have the timestamp and record ID.
Collect the relevant log entries
Extract the log lines from the time window around the reproduction that mention the record ID or the test user. Include SQL and failed-SQL entries only if the failure is a database error, because query text can contain personal data. Check the admin app log view for the same window as a cross-reference. Put the extract in the ticket or a restricted share, and keep it out of group chat. The step is done when the extract shows the failing request, the error message and the code location, and you have checked that it contains no passwords, tokens or session values.
Enable debug mode in staging or briefly in production
Reproduce the issue in a staging copy with the same EspoCRM version, extensions and masked data wherever possible. If production must be used, name one owner in the ticket, enable debug mode for the shortest window the test needs, and agree in writing who turns it off. Debug output can expose internal paths and queries, so confirm with the vendor docs whether it can be limited to the test user's session. The step is done when the owner has recorded the start time and the planned end time and the reproduction has been captured.
Revert debug mode and rotate logs
Turn debug mode off, restore the log level recorded in the second step, and confirm both values in the admin area or configuration file. Archive or rotate the verbose log so it is kept separately with restricted permissions and a retention period approved by your security team. Make a normal request and check that it logs at the standard level and that no debug output appears on user pages. The step is done when the change record shows the revert time, the archive location and permissions, and a fresh request behaves normally.
Protecting logs and keeping traces out of production
Logs and debug traces are useful during diagnosis and risky the rest of the time, because they can hold customer records, tokens and server paths. The cards below cover the exposures to check and the controls to put in place before a fault is ever investigated.
Personal data and tokens in logs
Application and SQL logs can capture request details, query parameters and error context that include customer names, email addresses, phone numbers or session and API tokens. Before enabling any verbose level, decide which fields may appear in a log and who may read them. Ask your EspoCRM partner or internal team to test a sample error with a fake customer record and confirm what lands on disk. Treat any log that contains a token as a credential that needs rotation.
World-readable log directories
The log directory must be writable by the web server or PHP user and unreadable by other local accounts. Check the owner, group and permissions of the EspoCRM data and log paths after every install, upgrade or restore, because a permissive umask or a copy made as root can quietly widen access. Confirm that web-accessible paths do not expose log files over HTTP, since a direct request to a log file would bypass every application access control.
Debug output exposed to users
Debug mode and verbose error display are meant for diagnosis, not for end users or portal visitors. Confirm that the production instance does not show stack traces, file paths or SQL statements in browser responses, and that the portal and API return generic error messages. Test this from an unauthenticated browser session and from a portal user account, since those are the paths most often overlooked.
Logs filling the disk
Verbose levels and repeated failures can grow log files quickly, and a full disk can stop the database, sessions and background jobs. Set a rotation or cleanup policy for the log directory, monitor free space on the volume that holds it, and reset the log level to the standard setting once an investigation closes. Ask whoever runs your hosting to alert on disk usage before it reaches a critical threshold.
Admin accounts for log access
Reading logs and switching debug settings should be limited to named administrators, not to the shared account used for daily work. The EspoCRM security guidance recommends avoiding admin accounts for routine tasks, so use a separate admin identity for diagnosis and record who changed the log level and when. Restrict admin access by IP address where your network allows it, and keep the break-glass account documented but disabled from password recovery.
Returning to production settings
Debug settings are easy to leave on after a fix, and a forgotten verbose level keeps leaking data long after the incident. Make reverting part of the change record: note the original level, the time it was raised, the person who raised it, and the step that lowers it again. Review the live configuration during the post-incident check and before any handover, so that the production state is confirmed rather than assumed.
Questions teams ask before diagnosing EspoCRM faults
How long does it take to diagnose an EspoCRM fault?
There is no fixed duration, because diagnosis time depends on how reproducible the fault is and how much evidence the system already holds. A fault that reproduces on demand with a clear error in the admin app log is usually quicker to isolate than an intermittent slowdown that appears only at month end. The main drivers are the number of customizations (custom entities, formula scripts, hooks and workflows), the number of environments you can test in, whether the logs were kept at a useful level before the incident, and how many systems are involved, such as mail servers, identity providers or external APIs. Ask any partner to state what evidence they need first and what they will deliver at the end of the investigation, in writing, before work starts.
Can an internal admin diagnose EspoCRM logs without a partner?
Yes, many faults can be found by an internal administrator who has shell access to the server and access to the admin panel. The admin UI app log shows recent application messages, and the log files on the server hold more detail, including failed SQL statements when that logging is enabled. Internal teams usually struggle with three things: reading PHP stack traces, changing log levels safely, and reproducing the fault in a non-production copy. A partner adds value when the fault involves custom code, database behavior or several connected services, or when the internal team needs an independent second look for an audit or incident record.
What access and information does a partner need to investigate?
A partner typically needs a time-bounded account with the access level the investigation requires, read access to the relevant log files, the EspoCRM version and PHP and database versions, a copy of custom entities, formulas, hooks and extensions, and a description of the symptoms with timestamps. Production data is rarely needed to find a cause, and personal data should be minimized or masked before it is shared. Agree on where investigation takes place (in your infrastructure or a copy of it), how logs and dumps are transferred, and how access is revoked afterwards. Confirm these terms in the written scope.
Is debug mode safe to enable in production?
Debug mode should not be left on in production. It can write detailed traces, including SQL and data values, to logs that more people can read than the EspoCRM data itself, and it can expose internal paths and errors to users. Enable it only for a bounded window, at the narrowest scope that reproduces the fault, with a named owner who turns it off again. Record the change, store the logs with the same access controls as customer data, and remove or rotate the traces once the diagnosis is closed. The EspoCRM security documentation is the right reference for how logging settings sit alongside your access policy.
What does a retainer cover compared with a one-off investigation?
A one-off investigation is scoped to a defined fault or set of symptoms, ends with a written findings report and agreed fixes or recommendations, and is priced from that written scope. A retainer is an ongoing arrangement for support, upgrades, monitoring reviews and incident response, usually with agreed response expectations and a regular review of logs and configuration. Ask each option to be spelled out: which systems are covered, how incidents are raised, who is on the request channel, what is billed as recurring and what is billed per piece of work, and what happens when a fix needs a change outside the retainer. Retainers are available from DeployOpen, and a quote follows from the written scope.
What drives the cost of an EspoCRM log investigation?
The cost is driven by the work involved, not by the log file itself. The larger components are the time to reproduce the fault, the number of custom components that need review, the number of integrations involved, and whether fixes must be built, tested and rolled out after diagnosis. Cost goes up when logs were not retained, when the fault can only be reproduced in production, or when several teams must give evidence. It goes down when you keep a current inventory of customizations, retain logs at a sensible level, and provide a staging copy. Request a quote that separates investigation, fix, and any follow-up testing.
What should we check before opening a support request?
Gather the EspoCRM version, the time the fault started, the exact error text, the user and record affected, and any recent changes such as upgrades, extensions, layout or formula edits, or server updates. Check the admin UI app log and confirm that the cron job or daemon is running, because many symptoms that look like application errors are scheduling issues. Keep a copy of the logs from the period of the incident before any rotation removes them. This preparation shortens diagnosis more than any other single step and makes the written findings clearer.
What a DeployOpen logging and debugging engagement includes
A DeployOpen logging and debugging engagement produces four deliverables: a review of the logging configuration on your EspoCRM instance, a written diagnosis runbook, a log retention and access plan, and a handover to your internal team. The review covers where EspoCRM writes its application log, which log level is set for normal operation, whether SQL and failed-SQL logging are enabled, and whether the admin UI app log is used by the people who will investigate problems. The runbook then turns those findings into steps your staff can follow: which log to check first for a failed save, a stuck workflow or an email that did not fetch, and when debug mode is appropriate and how to switch it off again.
The retention and access plan is where many teams find the most risk. Debug output can contain record data, email content and query parameters, so the plan states how long each log is kept, where it is stored, who can read it and how it is rotated or purged. It also lists the production settings that must be reverted after diagnosis. Your team receives the runbook, the reviewed configuration and a short walkthrough so that the next incident does not depend on the people who wrote the plan. Scope, deliverables and timelines are agreed in writing before work starts. Fixes for issues the review uncovers are scoped separately, so you can decide which findings to act on and who carries out each change.
Before requesting a quote, ask for the list of systems and environments in scope, the EspoCRM version and hosting model, and who on your side must approve changes to production logging. Confirm with your own security team how long logs may be retained under your policies and whether they must be sent to a central log platform. Those answers determine the depth of the review and the size of the handover, and they are the inputs a fixed-scope proposal needs.
How DeployOpen scopes and supports EspoCRM logs and debug mode
DeployOpen works on EspoCRM logs and debug mode inside your own infrastructure, starting from a written scope that names the log locations, levels and diagnostic settings to be covered. Each step ends in documentation your team can run and keep using after the engagement closes.
How we scope
- Inventory the EspoCRM version, PHP and database stack, and the servers where logs are written.
- Agree which symptoms to cover, such as failed SQL, app log errors or email and job failures.
- Define who may enable debug mode, for how long, and where diagnostic output is allowed to go.
- Fix the scope, deliverables and timeline in writing before any configuration change starts.
How we build
- Set log levels and log rotation in the EspoCRM configuration for your environment and retention needs.
- Enable SQL and failed-SQL logging in a test instance first, then confirm output volume and content.
- Document how to read the admin UI app log and map common entries to likely causes.
- Test the debug mode switch-off procedure so traces do not persist in production after diagnosis.
How we hand over
- Deliver a runbook covering log file paths, levels, rotation settings and the steps to change them.
- Walk your administrators through a diagnosis exercise using logs from a non-production instance.
- Record the production checklist for disabling debug mode and clearing diagnostic files after use.
- Confirm with your team which log access rights and retention periods apply under your own policies.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Support can cover review of logs after EspoCRM upgrades, extension changes or infrastructure moves.
- Ask any support provider to state in writing how log data is stored, accessed and deleted.
- Confirm response and escalation terms in the written agreement rather than assuming them.
