# Trouble with submodules **URL:** \ **Category:** Questions & Answers\ **Created:** [January 12, 2026, 2:20pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077 "2026-01-12T14:20:44Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![rvdalen](https://avatars.discourse-cdn.com/v4/letter/r/b4bc9f/32.png) [@rvdalen](https://racket.discourse.group/u/rvdalen)\ **Post date:** [January 12, 2026, 2:20pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/1 "2026-01-12T14:20:44Z")
Hi, I am having some trouble with submodules. The following short program gives an error in DrRacket 9.0: ```scheme #lang racket/base (require 'bar) (define (foo) "foo") (module bar racket/base (provide bar) (define (bar) "bar")) ``` It complains about: ```scheme require: unknown module module name: 'bar ``` Why does this code not work? Regards Rouan ---
**Author:** ![EmEf](https://avatars.discourse-cdn.com/v4/letter/e/53a042/32.png) [@EmEf](https://racket.discourse.group/u/EmEf)\ **Post date:** [January 12, 2026, 2:39pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/2 "2026-01-12T14:39:09Z")
Move the submodule to the top. The top-level forms of the outer modules are processed in order, meaning when Racket gets to `(require ‘bar)` it hasn’t seen `(module bar …)` yet. ---
**Author:** ![rvdalen](https://avatars.discourse-cdn.com/v4/letter/r/b4bc9f/32.png) [@rvdalen](https://racket.discourse.group/u/rvdalen)\ **Post date:** [January 12, 2026, 3:00pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/3 "2026-01-12T15:00:42Z")
Thanks. If I move it to the top then it works in DrRacket for this small example. I could not find anywhere in the official docs that there is a requirement that submodules must be defined before they are required. Did I miss it or is it undocumented? I also am trying to use submodules in a bigger project where I have lots of actual .rkt files. In 1 of the files I am trying to use submodules: ```scheme #lang racket/base (module tst2 racket/base (provide foo) (define (foo) "fooyoh")) (provide generate-data-entities) (require 'tst2 "../gunit/_module.rkt" "../../../sysmodel/core/_module.rkt" sunshine-fw/sourcecode/code/oo/ast/builder sunshine-fw/slib/data-struct threading racket/undefined) ``` Racket then gives me the error: ```scheme ../../../../bin/racket9_0/share/pkgs/errortrace-lib/errortrace/stacktrace.rkt:409:4: errortrace: unrecognized expression form at top-level: (module tst2 racket/base (#%module-begin (module configure-runtime (quote #%kernel) (#%module-begin (#%require racket/runtime-config) (#%app configure (quote #f)))) (#%provide foo) (define-values (foo) (lambda () (quote "fooyoh"))))) ``` Am I doing something wrong here? ---
**Author:** ![EmEf](https://avatars.discourse-cdn.com/v4/letter/e/53a042/32.png) [@EmEf](https://racket.discourse.group/u/EmEf)\ **Post date:** [January 12, 2026, 3:27pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/4 "2026-01-12T15:27:31Z")
I think we need more context to explain this error. When I comment out the collects and filed I don’t have, I get `generate-data-entities` not defined, as expected. It certainly has nothing to do with submodules. ---
**Author:** ![rvdalen](https://avatars.discourse-cdn.com/v4/letter/r/b4bc9f/32.png) [@rvdalen](https://racket.discourse.group/u/rvdalen)\ **Post date:** [January 12, 2026, 3:57pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/5 "2026-01-12T15:57:02Z")
Thanks, I dug a little deeper and narrowed the error I am getting to the import: ```scheme sunshine-fw/sourcecode/code/oo/ast/builder ``` That module exports an identifier called module which interfered with the Racket module form. If I import that module as prefixed, then my errors go away. Now the only thing I am still wondering is the requirement that a module must be defined before it is required. I would like the submodules at the bottom of the file not the top really. Is there no way to do this using the `(module)` form? ---
**Author:** ![ToddJonker](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/toddjonker/32/2452_2.png) [@ToddJonker](https://racket.discourse.group/u/ToddJonker)\ **Post date:** [January 12, 2026, 10:17pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/6 "2026-01-12T22:17:59Z")
This is an outcome of behavior documented in a few places, most clearly in [Module Expansion, Phases, and Visits](https://docs.racket-lang.org/reference/syntax-model.html#%28part._mod-parse%29): > A [require](https://docs.racket-lang.org/reference/require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) form not only introduces [bindings](https://docs.racket-lang.org/reference/syntax-model.html#%28tech._binding%29) at expansion time, but also visits the referenced module when it is encountered by the expander. In other words, the expander will attempt to locate the module's code as soon as it hits the `require` clause. Put another way, imports aren't "delayed" until after expansion, they happen on the go. `module` clauses work similarly, which is why you can `require` a module that's declared previously in the same file. ---
**Author:** ![rvdalen](https://avatars.discourse-cdn.com/v4/letter/r/b4bc9f/32.png) [@rvdalen](https://racket.discourse.group/u/rvdalen)\ **Post date:** [January 13, 2026, 1:37pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/7 "2026-01-13T13:37:36Z")
Thanks Todd, That explanation is not as straight forward for new devs learning Racket. I think it would be beneficial to update the Racket Guide or Racket Reference to actually state this explicitly. I will update my own Racket book with a more explicit explanation of define-a-module-before-requiring-it behaviour 🙂 I will go with putting the submodules at the top as this seems to be per-design of Racket. Thanks for everyone who put me on the right path. Always a pleasure to be part of the Racket community. ---
**Author:** ![EmEf](https://avatars.discourse-cdn.com/v4/letter/e/53a042/32.png) [@EmEf](https://racket.discourse.group/u/EmEf)\ **Post date:** [January 13, 2026, 2:23pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/8 "2026-01-13T14:23:17Z")
You may wish to look at [Modular Programming](https://felleisen.org/matthias/Thoughts/Modular_Programming.html). ---
**Author:** ![greghendershott](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/greghendershott/32/98_2.png) [@greghendershott](https://racket.discourse.group/u/greghendershott)\ **Post date:** [January 13, 2026, 3:38pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/9 "2026-01-13T15:38:33Z")
This might be more flexible than you're thinking? Just to make sure it's clear, you _don't_ have to put the submodules at the top. You merely need to `require` the submodule after its definition. So although you may, you don't _have_ to do: ```scheme #lang racket/base (module m racket/base (provide thing) (define thing 42)) (require 'm) thing ``` You may also do: ```scheme #lang racket/base thing (module m racket/base (provide thing) (define thing 42)) (require 'm) ``` There may also exist multiple `require`s, so it is not uncommon to see the following layout -- with most things required at the top, plus your submodule `require` below: ```scheme #lang racket/base (require racket/match foobar "some-file.rkt") thing (module m racket/base (provide thing) (define thing 42)) (require 'm) ``` * * * TL;DR: 1. If you prefer a "top-down" layout with "supporting"/"helper" definitions toward the bottom, and want to think of submodules like that, you totally can do that! 2. You can think of `(module m __) (require 'm)` as a pair you always do in that order, preferably right next to each other. You can put that pair, together, in that order, _anywhere_ at the file's top level. ---
**Author:** ![rvdalen](https://avatars.discourse-cdn.com/v4/letter/r/b4bc9f/32.png) [@rvdalen](https://racket.discourse.group/u/rvdalen)\ **Post date:** [January 13, 2026, 5:26pm UTC](https://racket.discourse.group/t/trouble-with-submodules/4077/10 "2026-01-13T17:26:28Z")
Thanks Greg, That is awesome and allows more flexible structuring of submodules. Hazaaaaa 🙂