add_moduleinfo: "Column 'module' cannot be null" — and the errors it hides

Root cause

What "Column 'module' cannot be null" actually means

add_moduleinfo() expects $moduleinfo->module to already contain the numeric id of the module type — the id column from the mdl_modules table. Setting $moduleinfo->modulename = 'page' is not enough. The function never looks the id up for you, because in normal life it doesn't have to: the course-edit form resolves it and posts it along with everything else. A CLI caller has no form, so nothing fills it in, and the INSERT INTO mdl_course_modules lands with module = NULL.

That's the whole first bug. One field.

Why every write after the first failure also fails

This is the trap that costs people the afternoon. add_moduleinfo() runs inside a delegated transaction. If it throws and your loop does the "sensible" defensive thing —

try {
    add_moduleinfo($mi, $course);
} catch (Exception $e) {
    mtrace('skipping broken module: ' . $e->getMessage());
    continue;   // <-- this line ruins the rest of your run
}

— you now have an aborted transaction that nobody rolled back, and every subsequent database write in the process fails. Each one reports the same generic "Error writing to database". So your log shows forty identical failures, and the one line that names the real problem is the first one, buried at the top.

We learned this the slow way: we spent time debugging module #2's "database error" when module #2 was completely fine. The corpse of module #1's exception was poisoning it.

The third trap is quieter: editor and file fields — page content, resource files — don't reliably persist when you hand-build the structures without a real draft itemid. No exception, no warning. Just empty modules. We'll fix that below.

The fix

The fields add_moduleinfo actually needs

Look the module id up by name, and set the generic fields the function assumes the form has provided. This is the block that ended our null-column errors for good:

require_once($CFG->dirroot . '/course/modlib.php');

$mi = new stdClass();
$mi->modulename = $modname;      // 'page', 'resource', 'forum', ...
$mi->course     = $course->id;
$mi->section    = $sectionnum;   // section NUMBER, not id
$mi->name       = $title;
$mi->visible    = 1;
$mi->introeditor = ['text' => '', 'format' => FORMAT_HTML, 'itemid' => 0];

// The one everyone misses — the numeric id, not the name:
$mi->module = $DB->get_field('modules', 'id', ['name'=>$modname], MUST_EXIST);

// also set the generic fields add_moduleinfo expects:
$mi->cmidnumber=''; $mi->groupmode=0; $mi->groupingid=0;
$mi->visibleoncoursepage=1; $mi->completion=0; $mi->completionexpected=0;
$mi->showdescription=0; $mi->availabilityconditionsjson=null;

$info = add_moduleinfo($mi, $course);

Why your page content and files come out empty

Editor fields (introeditor, page content) and file fields normally receive a draft itemid — a pointer to files the browser uploaded into the user's draft area, which Moodle then moves into the module's own filearea on save. Hand-built structures with a made-up itemid don't error. The move just silently doesn't happen.

We tried faking draft itemids first. Don't. The modules save, the run is green, and the content is gone.

Two routes actually work. The by-the-book route is a real draft area: file_get_unused_draft_itemid() plus a real user context, populate it with $fs->create_file_from_pathname(), pass that itemid in the editor array. It works, but it drags a fake "uploading user" into a CLI process.

The route we now use in CLI scripts is more direct: create the module first, then place files straight into the module's own filearea and set the content column:

$fs  = get_file_storage();
$cm  = get_coursemodule_from_instance('page', $pageid);
$ctx = context_module::instance($cm->id);

$fs->create_file_from_pathname((object)[
    'contextid'=>$ctx->id, 'component'=>'mod_page', 'filearea'=>'content',
    'itemid'=>0, 'filepath'=>'/', 'filename'=>$name], $localpath);

// $html references the file with the placeholder Moodle rewrites at
// render time, e.g.  <img src="@@PLUGINFILE@@/diagram.png">
$DB->set_field('page', 'content', $html, ['id'=>$pageid]);

The @@PLUGINFILE@@ token is the important part: Moodle rewrites it to a real pluginfile.php URL when the page renders, so the same content works regardless of wwwroot. Store the literal token in the database, never a hardcoded URL.

When to script it and when to call someone

Everything above is enough to build courses in code reliably — that's why we wrote it down. The pattern (numeric module id, fail fast, files straight into the module filearea, @@PLUGINFILE@@ in content) has held up for us across thousands of generated modules. But if you're staring at a bulk import that has to land clean — hundreds of courses, mixed module types, source content in odd formats — that's the kind of Moodle development work we do every week, and course-generation scripts are among our favorite jobs precisely because the traps are so well mapped. Tell us what you're importing and we'll reply within one business day with an honest read on whether you need us at all.

Quick answers

Questions people ask about this