Abstract

Introduction
Many Stata runtime errors can be easily fixed. A quick look at the syntax may reveal a missing comma, an unmatched parenthesis, or a misspelled option.
Errors such as the following, however, can be far more perplexing. Suppose that after running a program seemingly forever, Stata finally gives the message
which usually means that even if you did get results, you cannot trust them.
Convergence problems can have any number of causes. The model may be fundamentally flawed. The syntax may not specify the model correctly. There could be problems with the data. There may be too many variables in the model for Stata to handle. The sample size could be too big for the given task or too small. The statistical technique employed may not be the optimal one for this topic. Perhaps most frustrating of all, the user may be doing everything right, but the software could be buggy.
There can be other seemingly inexplicable errors where Stata provides little or no guidance for addressing the problem. A personal favorite: Stata suddenly starts spewing messages in red that mean little to me (something about overflow problems) and then aborts. I assume that Stata has encountered an error that it has failed to trap and give an informative error message for, but that does not do me any good in trying to figure out what to do about it.
It is easy to spend hours trying to solve convergence problems. Before doing so, however, I suggest trying some of the tips (arranged roughly in order of difficulty) given below. They might lead to a simple solution to the problem or at least provide a template for identifying where the problem is. Some of these tips may also help when other seemingly inexplicable errors are encountered. Many of these tips may seem obvious, but I have encountered numerous instances where less experienced users knew nothing about them and even experienced users failed to try them.
Tips
1.
This tip may seem too obvious, but not everyone follows it or even knows about it. Statalist occasionally has postings reporting a strange problem followed by a comment that the problem was fixed days earlier in the most recent maintenance release (or will be fixed in the next one). Speaking from personal experience, a user reported a problem with my
Also, if you are using an older version of Stata, see whether the problems persist in newer versions. I have had students come in with hand-me-down versions of Stata 12. One of the first things I do is see whether I have the same problem with my version of Stata. I do not want to spend hours trying to solve a problem that StataCorp took care of 10 years ago. Conversely, if a command worked in the past, it sometimes helps to run it in an older version of Stata because new bugs can inadvertently get introduced.
2.
It can also sometimes help to subtract a constant from a variable. Variables like
then the new variable will have values ranging from 1 to 20, which Stata may find much easier to work with.
The choice of what constant to use is up to the researcher. Particularly when 0 is an impossible value (for example, nobody weighs 0 pounds), centering the variable by subtracting the mean from each case is often a popular choice. Then a value of 0 on the new variable means the person had the average score on the original variable, while a negative or positive value indicates that the respondent had a below average or an above average score.
I have seen many instances where rescaling variables instantly solved convergence problems. Furthermore, whether you have convergence problems or not, you may want to rescale some variables for presentation purposes anyway. It may seem bizarre if the effect of income in dollars is reported as 0.000 and is significant at the 0.001 level. Income in thousands of dollars may instead yield a much more understandable coefficient, such as 0.412.
Rescaling is not always a good idea though. For example, with count models, any transformation of the dependent variable (for example, number of doctor visits) can be a serious mistake and violate the assumptions of the method. The user needs to understand what variable transformations are appropriate given the method used.
3.
A reviewer noted (and my own experience confirms) that the
Some people may be reluctant to use the
will cause Stata to first try the Newton-Raphson algorithm, followed by the Berndt-Hall-Hall-Hausman algorithm, and then finally the Broyden-Fletcher-Goldfarb-Shanno algorithm.
You can also try other maximization options, like increasing the number of iterations, changing the start values, or adjusting the tolerance levels. I rarely, if ever, have any luck with these methods, but they could help in some situations. To learn more, type
4.
This tip may also seem too obvious—it is basically Data Management 101—but students in statistics classes are used to solving textbook problems where the data are in perfect shape, and even experienced users (especially those working on a research team) may just assume that somebody else has adequately prepared the data. Be wary, too, of downloaded data. Even if the data are already in Stata
As an instructor, one of the first things I make students do is run descriptive statistics on their variables, for example, use commands like
5.
6.
Also, Stata has commands specifically designed to deal with rare events, for example, a dichotomy where 99% of the cases are coded 0 and only 1% are coded 1. See Leitgob (2020) and Allison (2012) for discussions.
7.
8.
One of the above tips will hopefully provide a relatively quick and painless fix. But if problems persist, below are some more.
9.
When building a model gradually, ensure that the same cases are being analyzed throughout because adding a new variable that has missing data can cause the sample size to shrink. This can be especially problematic if the new variable was only measured for a subsample of the respondents, for example, women. The
will enter
10.
11.
Researchers are understandably reluctant to drop variables, but they should not let the perfect be the enemy of the good: fitting a simplified model will generally be better than fitting no model at all. The user can always explain in the text why a variable was not included in the final model but was adequately examined in the earlier analysis.
12.
Finally, if all else fails, there is one last suggestion:
13.
Conclusions
Convergence problems and other seemingly inexplicable errors can be baffling at first, and you could easily spend hours trying to figure them out. Before doing so, however, see if there are simple solutions that work. If you update your software, you may find that your problem has already been fixed. The
Do not be too wedded to your model. Like it or not, some variables may need to be dropped because they are too poorly measured or contribute nothing to the analysis and may even make it difficult to get any estimates at all.
Consider alternative methods and software programs. They may be able to handle tasks that your current program is struggling with and may even be more appropriate in some cases.
Finally, be open to the possibility that your theory is wrong, and even if it is not, you may not have the data needed to estimate it. Consider what you can do instead or what you need to do differently in the future.
Acknowledgment
The author thanks Richard Campbell for his helpful comments and suggestions.
Supplemental Material
sj-txt-1-stj-10.1177_1536867X261425756 - Supplemental material for Stata tip 167: Dealing with convergence issues and other seemingly inexplicable problems
Supplemental material, sj-txt-1-stj-10.1177_1536867X261425756 for Stata tip 167: Dealing with convergence issues and other seemingly inexplicable problems by Richard Williams
References
Supplementary Material
Please find the following supplemental material available below.
For Open Access articles published under a Creative Commons License, all supplemental material carries the same license as the article it is associated with.
For non-Open Access articles published, all supplemental material carries a non-exclusive license, and permission requests for re-use of supplemental material or any part of supplemental material shall be sent directly to the copyright owner as specified in the copyright notice associated with the article.
