Matlab Debugging

Matlab Debugging - Troubleshooting and Errors

This page looks specifically at how to troubleshoot Matlab problems - how to get more information, how to read and interpret error messages, and how to dig through m-files to find what's gone wrong. For the most basic of basics, check out MatlabBasics. As well, MatlabPaths answers questions about modifying your search paths, and MatlabProgramming talks about how to read m-files and how to program with them.

In the following, text in fixed-width font are commands that you can type directly into Matlab.

Troubleshooting SPM and Matlab

So there you are, tootling along estimating your model or coregistering your anatomy or what have you. And then, boom: computer beeps, error message pops up, everything stops, fire and brimstone come from the sky. What can you do about it? Lots, as it turns out. Armed with a sense of the Matlab basics and understanding of Matlab code, you can often divine a lot about what's going on in your error from your crash - often enough to fix the problem, but at least enough to narrow down the possibilities. The two crucial entry strategies to troubleshooting are: knowing where the problem happened, which frequently boils down to interpreting your error messages, and knowing what was happening when the problem hit, which relies on Matlab's debugging package. We'll tackle them separately.

  • Non-errors

    Before we jump into errors, a quick word about non-error problems. Warnings sometimes crop up in Matlab, and they allow the program to continue. They're not generally anything worth worrying about - they'll let the program run - but they're worth noting, and trying to understand what they mean, particularly when they precede an error. The programmer puts warnings in for a reason, to notify you of something weird happening, so listen to her...

    Also, people sometimes ask whether they can tell if an SPM program is crashed or just running for a long time. In the non-graphical version, it's difficult to tell - the Linux command "top" can sometimes tell you something - but in the graphical version, the status bar at the bottom of the window is a good indicator. If the program's working on something, it'll say "Busy" down there; if it's not, it won't. In general, Matlab rarely crashes outright without generating some kind of error message, so if something's stopped responding and you've got a "busy" message but no error message, it's probably still working. If it seems like it's been going for an inordinate amount of time, though, check in with somebody.

  • Where did the error happen? or, Everything you need to know about error messages

    SPM errors can happen in terribly uninformative fashion. Everyone who's used SPM has seen the infamous "Error during uicontrol callback," which is a generic Matlab error that means "Something went wrong in the function called by pushing whatever button you just pushed." Fortunately, Matlab has relatively well-designed error-detection and bug-tracking facilities. You can learn a great deal about your error just by interpreting your error message.

    Sometimes in SPM you'll get a full error message of several lines, but oftentimes you'll get the one-line "uicontrol callback" error. However, if you close the panel that's home to the button that generated the error, you can often get the full underlying error message. So if you hit "volume" in the results section and get a uicontrol callback error, closing the results panel will usually generate further information about the error. You may also be able to generate more information simply by going to the Matlab window and hitting return a couple of times. Always try and get a full error message when you have an error! Even if you can't figure out the problem, it's almost totally useless to another troubleshooter if you come to them and say, "I have an error!" or "I have a uicontrol callback error!" without any more information about the problem. Gather as much information about the error as you can - the Matlab window is your friend.

    Matlab error messages are of varying helpfulness, but they all follow the same structure, so let's take a look at one:

??? Error using ==> spm_input_ui Input window cleared whilst waiting for response: Bailing out!

Error in ==> c:\documents and settings\jeff cooper\my documents\gablab\spm99\spm_input.m On line 77 ==> [varargout{:}] = spm_input_ui(varargin{1:ib-1});

Error in ==> c:\documents and settings\jeff cooper\my documents\gablab\spm99\spm_get_ons.m On line 146 ==> Cname{i} = spm_input(str,3,'s',sprintf('trial %d',i),...

Error in ==> c:\documents and settings\jeff cooper\my documents\gablab\devel_99\spm_fMRI_design.m On line 225 ==> [SF,Cname,Pv,Pname,DSstr] = ...

Error in ==> c:\documents and settings\jeff cooper\my documents\gablab\devel_99\spm_fmri_spm_ui.m On line 289 ==> [xX,Sess] = spm_fMRI_design(nscan,RT);

??? Error while evaluating uicontrol Callback.

SPM errors will often look like this one: a "stack" of errors, although the stack may be bigger or smaller depending on the error. So what does it mean?

First, the order to read it in. The top of the stack - the first error listed - is the most immediate error. It's what caused the crash. Matlab will tell you what function the error was in - in this case, it's spm_input_ui - and some information about what the error was. That error message may be written by the function's programmer (in which case it's often quite specific) or be built-in to Matlab (in which case it's usually not). Sometimes that top error may also give you a line number on which the error was generated within the function.

The rest of the stack is there to tell you where the function that crashed was called from. In this case, the next one down the stack was in spm_input - so our error was in spm_input_ui, which was called by spm_input. The line in spm_input that calls spm_input_ui is highlighted for us - it's line 77 within spm_input.m. The next error down tells us that spm_input was itself called from within spm_get_ons, on line 146, and so on. The last error tells us that the very first function that was called was spm_fmri_spm_ui - that's the function that was called when we first hit a button.

From only this limited information, you can often tell a lot about the error. One important distinction to draw is whether the function where the error happened was an SPM function or a Matlab function. Built-in Matlab functions are generally pretty stable, and so if they crash, it's usually because you, the user, made a mistake somewhere along the line. Functions that commonly error in Matlab include:

  • load - if the files it's trying to load don't exist or have been renamed or moved, or if they're corrupted.
  • save - if the directory you're trying to save to doesn't have write permission, or if you're out of disk space, etc.
  • copyfile, delete, movefile - these sometimes crash because of bugs in Matlab.

When the function that generated the error is an spm function, or a Gablab-written function, you can usually tell - it'll have the prefix 'spm_' or 'roi_' on it, or generally sound like something from fMRI analysis and not Matlab generally. In this case, the error is sometimes in the code and sometimes a mistake earlier in your analysis. The error messages can sometimes tell you enough to figure out what's going on: perhaps it says that there's an index out of range, and you realize it's because you're trying to omit the 200th scan from a session that only has 199. Just looking at the line that generated the error and what the actual error message says can give you a lot of info off the bat. Study the message carefully and look at the function stack it came from and see if you can figure out what the program was doing when it crashed.

It's not always enough to look at the problem after it's crashed, though. Sometimes you need to figure out what's happening when it actually crashed, and in that case, you need Matlab's debugging package.

  • Matlab Debugging

    Matlab's debugging package is pretty good. Hard-core debugging is a skill that's acquired only after a lot of programming, but even someone brand-new to reading code can use some debugging techniques to make sense of what's going on with their data, and hopefully learn some details about Matlab code at the same time...

    You'll need to be running the graphical version of Matlab to take real advantage of Matlab's debugging; without it the text editor won't open and you won't be able to see the details of the function you're debugging.

    The starting point for any bug-finding expedition is to answer the question, "What was happening in the program when it crashed?" The hope is answering that will tell you why it crashed, and how to keep it from crashing again. When errors ordinarily occur in Matlab, they end the execution of the program and close the workspace of the error-ing function, losing all its variable and so forth. The debugging package allows you, instead, to wait for an error and then "freeze" the program when one happens, holding it still so you can examine the state of all its variables and data.

    If you want to try debugging an error, figure out when your error happens first (during model estimation or when you push "load" or whatever). Then type "dbstop if error" at the Matlab prompt. This will engage the debugger in "waiting" mode. Then run your program again and do whatever caused the error. This time, you'll get an error message, but the prompt will change to K>>, and a text window will pop open containing the function that caused the error. The K prompt means you have Keyboard control - the program is frozen, and you can poke around as much as you like in it. To end the program when you're done debugging, type "dbquit" at the K>> prompt, and the program will end.

    Once you have the program frozen, it's time to look around. Check out the line that generated the error and see if you can figure out what the error message means. If it's called by an error function, is it inside an if block? If so, what condition is the if block looking for? If the error is caused by an index out of range, can you figure out what the index variable is? What is its value? What is the array that it's indexing? What sort of information is in there? Type whos to figure out what variables are currently in the workspace and what types they are, and type the name of variables to find out their values.

    It may not be immediately clear why a variable has the value it does or what it represents. Try reading line-by-line backwards through the function and find out when the variable got its current value assigned. Where did it come from? Are there any comments around it telling you what it is? Are there any comments at the top of the function describing it? This is where the programmer's cheat sheet (soon to be posted, ask Jeff for copies) can be particularly helpful.

    Sometimes a variable may have a strange value passed into it by whatever function called the error-ing function. The Matlab debugger has frozen that function as well, and you can move 'up' into its workspace to take a look around in the same way. Type "dbup" at the K>> prompt, and you'll switch into the workspace of the function that called the current one. You can go up all the way to the base workspace, and "dbdown" will let you switch back down through the stack. Remember that each workspace is separate - their variables don't interact, at least when all the m-files are functions.

    There are other debugging commands as well, more useful for you in writing your own scripts. Check out the Matlab help for keyboard, dbcont, dbstep and things like that.

    There's not more specific debugging advice to give, besides go explore the function. Every error is a little different, and it's impossible to tell what caused it until you get into the guts of the program. Good luck!