Diagnosing Stata Maximum Likelihood Convergence Failures: A Systematic Guide for Versions 16–18

Recognizable Symptoms

Your ml model stops with "convergence not achieved", "backed up" messages, or "initial values not feasible". The iteration log shows the log-likelihood changing by less than 1e-6 over dozens of iterations, or the gradient barely moves. In the output table, standard errors are missing or confidence intervals span orders of magnitude. These patterns appear across Stata 16, 17, and 18 when the optimizer cannot find a stable maximum.

Cause and Diagnostic Quick-Reference

Ordered Troubleshooting Checks

1. Validate the evaluator. Run ml check. It executes your likelihood evaluator at the current parameter vector and reports missing values, NaNs, or infinities. If this fails, fix the evaluator before proceeding.
2. Inspect the optimization path. Use ml trace to print each iteration’s log-likelihood, gradient norm, and parameter changes. Add ml graph to plot the likelihood surface along the search direction. A flat trace or zig-zag pattern signals scaling or concavity problems.
3. Compare variable scales. Execute summarize on every covariate. If the ratio of largest to smallest standard deviation exceeds 1e4, rescale (see Fixes).
4. Test for separation. For binary models, run logit y x, iterate(0). If coefficients are huge (|b| > 15) or standard errors are missing at iteration 0, separation is present.
5. Evaluate gradient and Hessian at the start. ml score and ml hessian return the gradient vector and Hessian matrix at the initial values. A Hessian with negative eigenvalues or a condition number > 1e12 confirms numerical instability.

Targeted Fixes Matched to Findings

1. Poor Starting Values

Supply better initial values via ml init or run a quick OLS/linear probability model first, then feed those coefficients to ml. Example:

regress y x1 x2
matrix b = e(b)
ml model lf myll (y = x1 x2)
ml init b
ml maximize

In Stata 17+, ml maximize, technique(switch) automatically cycles through NR, BHHH, DFP, BFGS if the default Newton-Raphson stalls.

2. Scale Mismatch

Rescale covariates so their standard deviations are within a factor of 100. Divide by 10k or by the variable’s SD. After estimation, recover original-scale marginal effects with margins, expression().

gen x1_scaled = x1 / 1000
ml model lf myll (y = x1_scaled x2)
ml maximize
margins, expression(normalden(xb())*_b[x1_scaled]/1000)

3. Perfect Prediction / Separation

Install firthlogit from SSC (ssc install firthlogit) and run the penalized likelihood estimator. It adds a Jeffreys prior penalty that bounds the likelihood. Compare AIC/BIC with the unpenalized model and disclose the penalization in any write-up.

firthlogit y x1 x2
estat ic

4. Non-Concave Regions ("Backed Up")

Switch optimization techniques explicitly:

ml maximize, technique(nr bhhh dfp bfgs) difficult

The difficult option reduces step size and increases iteration tolerance. In Stata 16 the default changed from technique(nr) to technique(nr bhhh); Stata 17+ adds technique(switch) for automatic cycling.

5. Numeric Overflow in User Evaluator

Rewrite the evaluator in Mata using double precision and robust exp()/log() calls (e.g., log1p(), exp() with bounds). Mata’s optimize() gives finer control but requires manual gradient coding. Avoid ado-file evaluators for production work—they run slower and invite copy-paste errors.

Escalation Criteria

Engage StataCorp support when all three conditions hold after two technique switches and rescaling:

• Log-likelihood changes < 1e-6 over 50 consecutive iterations.
• Hessian remains non-positive-definite (negative eigenvalues persist).
• Evaluator produces NaN or Inf at any parameter vector.

Provide: the ml trace log, a minimal data excerpt (preserving scale/separation pattern), and the complete do-file.

Practical Verification: Minimal Reproducible Example

Create a do-file that reproduces the failure and confirms the fix. Use set seed 123 for reproducibility.

clear
set seed 123
set obs 500
gen x1 = rnormal(0,10000)   // huge scale
gen x2 = rnormal(0,1)
gen y = (x1/10000 + x2 + rnormal() > 0)

// Deliberately ill-scaled logit
logit y x1 x2, iterate(20) trace
// Observe: "convergence not achieved", huge SE on x1

// Fix: rescale x1
gen x1_sc = x1 / 10000
logit y x1_sc x2, iterate(20) trace
// Confirm: "convergence achieved", reasonable SEs

// Recover original-scale marginal effect
margins, expression(normalden(xb())*_b[x1_sc]/10000)
postfile results model converged using verify.dta, replace
post results ("original") (0)
post results ("rescaled") (1)
postclose results

Document the steps, the ml trace output before and after, and the final margins result in your team wiki.

Limitations and Cautions

• Rescaling changes interpretation. Always report marginal effects on the original scale using margins, expression().
• Firth penalization alters the likelihood. Compare AIC/BIC with the unpenalized model; disclose the penalty in publications.
• Switching to BHHH can mask misspecification. Run linktest and hosmerlem after convergence.
• Large datasets (>1M obs) may hit memory limits during Hessian calculation. Use ml maximize, difficult sparingly and monitor memory.
• Version differences: Stata 16 default technique is nr bhhh; Stata 17+ adds technique(switch). Verify with help ml_maximize.

Verification Checklist

1. Run which ml and ml version to confirm Stata 16–18 syntax.
2. Execute help ml_maximize and verify technique() options match this guide.
3. Test the diagnostic sequence on Stata’s auto dataset with an ill-scaled logit:

   sysuse auto
   ngen mpg100 = mpg*100
   logit foreign mpg100 weight, iterate(20) trace

4. Confirm firthlogit availability: which firthlogit (requires SSC install).
5. Check Mata optimizer reference: help mata optimize() for alternative implementation path.