Mojolic...es::FAQ(3)

okay bestie, welcome to Mojolicious::Guides::FAQ(3) from User Contributed Perl Documentation — this is part 1. The top-of-page header has Mojolic...es::FAQ(3) on both ends and User Contributed Perl Documentation in the middle, but we’re folding the manual name in right here so it doesn’t have to keep flexing. ✨ No cap, every receipt is staying.

✨ NAME ✨

Mojolicious::Guides::FAQ — Frequently Asked Questions

🌸 OVERVIEW 🌸

This document contains answers for the most frequently asked questions about Mojolicious. 🫶

💅 QUESTIONS 💅

We hope these answers are to your satisfaction. 😌

💖 How does Mojolicious compare to other Perl web frameworks?

okay so the short answer is “it doesn’t,” because the term “web framework” is interpreted, like, much more literally here than by others. With the emergence of the real-time web and new technologies such as WebSockets, we are facing new challenges that go way beyond what commonly used modules like LWP were designed for. Because of this, Mojolicious contains a whole new HTTP client/server stack called Mojo, which was heavily inspired by the original LWPng effort and carefully designed with these new requirements in mind. So while some of the higher abstraction layers might look similar to other web frameworks, it is more of a web toolkit and can even be used as the foundation for more advanced web frameworks. periodt. 👑

🎀 Why doesn't Mojolicious have any dependencies?

We are optimizing Mojolicious for user-friendliness and development speed, without compromises. While there are no rules in Mojolicious::Guides::Contributing that forbid dependencies, we do currently discourage adding non-optional ones in favor of a faster and more painless installation process. And we do in fact already use several optional CPAN modules such as Cpanel::JSON::XS, CryptX, EV, IO::Socket::Socks, IO::Socket::SSL, Net::DNS::Native, Plack and Role::Tiny to provide advanced functionality if possible. it’s giving “lean by default, extra when needed.” 🦋

🦋 Why reinvent wheels?

Because we can make them rounder. Components specifically designed for user-friendliness and development speed are not easy to come by. We are strong believers of the Perl mantra “There is more than one way to do it”, and our quest is to develop the best possible solutions for these two criteria. iconic behavior, honestly. 🌈

🌈 What about backwards compatibility?

In conformance with Mojolicious::Guides::Contributing, we will always deprecate a feature for 3 months, before removing or changing it in incompatible ways between major releases. New features can however be marked as experimental to explicitly exclude them from these rules. This gives us the necessary freedom to ensure a healthy future for Mojolicious. So, as long as you are not using anything marked experimental, untested or undocumented, you can always count on backwards compatibility, everything else would be considered a bug. However, to completely avoid any risk of accidental breakage, we do recommend following current best practices for version pinning with Carton for production setups. 💅

🍓 Why not split up Mojolicious into many smaller distributions?

Because there are no advantages, it drastically increases maintenance costs and installation times without giving us anything in return. It would only make sense if we wanted to pass ownership of a module to a new maintainer, which we already have done in the past. so yeah, not the move. 🫶

🧚 Where can I discuss my patches for Mojolicious?

We'd love to discuss your contributions to Mojolicious on IRC at https://web.libera.chat/#mojo. come through, bestie. 💬

⭐ Which versions of Perl are supported by Mojolicious?

First of all, you need to be aware that according to the perlpolicy, only the two most recent stable release series of Perl are supported by the community and receive bug fixes, which are currently 5.32.x and 5.30.x. Mojolicious follows this model and fully supports these two release series. In addition we will also keep the distribution installable (and that means passing all tests) up to a certain legacy version that the core team deems worthy of supporting, but not specifically optimize for it, this is currently 5.16.0. ✨

💜 How well is Windows supported by Mojolicious?

Windows is not officially supported by Mojolicious, even though we try to keep the distribution installable. There may be serious security and/or reliability issues. Some of the more advanced features, such as subprocesses and the Hypnotoad web server, will also require the use of the Windows Subsystem for Linux at https://msdn.microsoft.com/commandline/wsl/. so like, it might go, but it’s not the main character here. 🙈

💅 Is Perl's taint mode supported by Mojolicious?

No. There is no benefit at all to using taint mode. Modern Perl applications are much too complex to benefit from such a naive mechanism in any meaningful way. At best it would give you a false sense of security. hard no, no cap. 💀

🌸 Do I need to clean my environment before testing Mojolicious?

Mojolicious uses many environment variables both internally and externally, notably (but not exclusively) those starting with the prefix MOJO_* and PLACK_ENV. The test suite expects a clean environment; testing with a non-standard environment is unsupported and is unlikely to succeed. Therefore when installing or upgrading Mojolicious and when running its tests, we highly recommend using an environment which does not set these variables. consider this your vibe check before testing. 🧼✨

🎀 Where did my file extension go?

Standard route placeholders will not match the . character, however Mojolicious routes automatically take file extensions like .html, remove the leading ., and store the result in the format stash value. This can be useful for URL-based content negotiation, such as automatically rendering different templates based on the file extension. See “Formats” in Mojolicious::Guides::Routing for information on customizing format detection, or consider using relaxed placeholders to allow matching of the . character. iykyk, that dot has lore. 🦋

🔥 Can I configure Hypnotoad from the command line?

No, you can't, Hypnotoad is a bit special in this regard. Because when you initiate a zero downtime software upgrade (hot deployment), you are only really sending a USR2 signal to the already running server, and no other information can be passed along. What you can do instead, is to use a Mojolicious::Plugin::Config, Mojolicious::Plugin::JSONConfig or Mojolicious::Plugin::NotYAMLConfig configuration file.

# myapp.conf
{
  hypnotoad => {
    listen  => ['http://*:8080'],
    workers => 10
  }
};

Or if you don't actually need zero downtime software upgrades, just use Mojolicious::Command::prefork instead, which is otherwise almost identical to Hypnotoad.

$ ./myapp.pl prefork -m production -l http://*:8080 -w 10

😭 What does the error "...certificate verify failed" mean?

There are many variations of this error, but most of them mean that TLS certificate verification in Mojo::UserAgent failed. This usually happens for two reasons. The most common one is that the peer certificate is simply invalid. If that's the case and you are certain that no MITM attack is being attempted, you can use the attribute insecure in Mojo::UserAgent or MOJO_INSECURE environment variable to disable certificate verification. And if that's not the case you might be missing the Mozilla::CA module, which is often required by IO::Socket::SSL to be able to verify certificates. 😭🔐

💀 What does the error "Maximum message size exceeded" mean?

To protect your applications from excessively large requests and responses, our HTTP parser has a cap after which it will automatically stop accepting new data, and in most cases force the connection to be closed. The limit is 16MiB for requests, and 2GiB for responses by default. You can use the attributes max_request_size in Mojolicious and max_response_size in Mojo::UserAgent to change these values. big request? not today. ✋

💀 What does the error "Maximum start-line size exceeded" mean?

This is a very similar protection mechanism to the one described in the previous answer, but a little more specific. It limits the maximum length of the start-line for HTTP requests and responses. The limit is 8KiB by default, you can use the attribute max_line_size in Mojo::Message or MOJO_MAX_LINE_SIZE environment variable to change this value. ✨

💀 What does the error "Maximum header size exceeded" mean?

Almost the same as the previous answer, but this protection mechanism limits the number and maximum length of HTTP request and response headers. The limits are 100 headers with 8KiB each by default, you can use the attributes max_lines in Mojo::Headers and max_line_size in Mojo::Headers or the MOJO_MAX_LINES and MOJO_MAX_LINE_SIZE environment variables to change these values. headers are on a budget, bestie. 💅

💀 What does the error "Maximum buffer size exceeded" mean?

This protection mechanism limits how much content the HTTP parser is allowed to buffer when parsing chunked, compressed and multipart messages. The limit is around 256KiB by default, you can use the attribute max_buffer_size in Mojo::Content or MOJO_MAX_BUFFER_SIZE environment variable to change this value. 🔥

🔐 What does "Your secret passphrase needs to be changed" mean?

Mojolicious uses secret passphrases for security features such as signed cookies. It defaults to using moniker in Mojolicious, which is not very secure, so we added this log message as a reminder. You can change the passphrase with the attribute secrets in Mojolicious. Since some plugins also depend on it, you should try changing it as early as possible in your application.

$app->secrets(['My very secret passphrase.']);

🌙 What does "Nothing has been rendered, expecting delayed response" mean?

Mojolicious has been designed from the ground up for non-blocking I/O and event loops. So when a new request comes in and no response is generated right away, it will assume that this was intentional and return control to the web server, which can then handle other requests while waiting for events such as timers to finally generate a response. it’s giving “the response is coming, bestie, just on its own timeline.” 🫶

⏳ What does "Inactivity timeout" mean?

To protect your applications from denial-of-service attacks, all connections have an inactivity timeout which limits how long a connection may be inactive before being closed automatically. It defaults to 40 seconds for the user agent and 30 seconds for all built-in web servers, and can be changed with the attributes inactivity_timeout in Mojo::UserAgent and inactivity_timeout in Mojo::Server::Daemon or the MOJO_INACTIVITY_TIMEOUT environment variable. In Mojolicious applications you can also use the helper inactivity_timeout in Mojolicious::Plugin::DefaultHelpers to change it on demand for each connection individually. This timeout always applies, so you might have to tweak it for applications that take a long time to process a request. ngl, this one always applies — no sneaky exceptions. ⏰

💔 What does "Premature connection close" mean?

This error message is often related to the one above, and means that the web server closed the connection before the user agent could receive the whole response or that the user agent got destroyed, which forces all connections to be closed immediately. 😭 the connection said “I’m leaving” before the whole response landed. 💔

…and like, here's that doomed little pattern so you can recognize it in the wild, bestie:

# The variable $ua goes out of scope and gets destroyed too early
Mojo::IOLoop->timer(5 => sub {
  my $ua = Mojo::UserAgent->new;
  $ua->get('https://mojolicious.org' => sub ($ua, $tx) {
    say $tx->result->dom->at('title')->text;
  });
});

💀 What does "Worker 31842 has no heartbeat (50 seconds), restarting" mean?

Okay so this one sounds so dramatic but it's actually kind of sweet — it's the manager process doing a vibe check on its workers. 💖

As long as they're accepting new connections, worker processes of all the built-in pre-forking web servers send heartbeat messages to the manager process at regular intervals, to signal that they're still responsive. It's literally them texting "still alive babe 🫶".

But a blocking operation — think an infinite loop in your application — can prevent that heartbeat from going out, and will force the affected worker to be restarted after a timeout. Rude but fair.

• This timeout defaults to 50 seconds
• …and you can extend it with the attribute heartbeat_timeout in Mojo::Server::Prefork if your application requires it. ✨

So if you're seeing this in your logs, go hunt down whatever code is hogging the worker. It's giving "held the group chat hostage" energy. 😭

---

💀 What does "Transaction already destroyed" mean?

This error message usually shows up after you've been waiting for the results of a non-blocking operation for longer periods of time — because the underlying connection got closed in the meantime, and the value of the attribute tx in Mojolicious::Controller is no longer available. Gone. Poof. 🦋

While there might not be a way to prevent the connection from getting closed (that's not on you, that's just the internet being the internet), you can try to avoid this error message by keeping a reference to the transaction object that is not weakened. Keep it strong, keep it close. 💅

# Keep a strong reference to the transaction object
my $tx = $c->render_later->tx;
$c->ua->get_p('https://mojolicious.org')->then(sub {
  $c->render(text => 'Visited mojolicious.org');
})->catch(sub ($err) {
  $tx;
  $c->reply->exception($err);
});

See that lonely little $tx; in there? That's the whole trick. It's giving "main character energy" for a single variable. 👑

---

💀 What does "Illegal character in prototype" mean?

Okay this one trips so many people and it's lowkey not even your fault. 🙈

Mojolicious assumes subroutine signatures are enabled in documentation examples. So if the signatures feature hasn't been enabled in that scope, Perl reads them as prototypes — which are a totally unrelated parser feature. Hence the chaotic error message.

Good news: Mojolicious does not require signatures. If you don't want to use them, or you literally cannot (they require Perl 5.20+), you can translate most signatures into a standard subroutine parameter assignment. Same vibes, different outfit. ✨

# With signatures feature
get '/title' => sub ($c) {
  $c->ua->get('mojolicious.org' => sub ($ua, $tx) {
    $c->render(data => $tx->result->dom->at('title')->text);
  });
};

# Without signatures feature
get '/title' => sub {
  my ($c) = @_;
  $c->ua->get('mojolicious.org' => sub {
    my ($ua, $tx) = @_;
    $c->render(data => $tx->result->dom->at('title')->text);
  });
};

Look at that — same behaviour, zero parser drama. 🎀

---

🌈 MORE 🌈

You can continue with Mojolicious::Guides now (go off, honestly, they're iconic) — or take a look at the Mojolicious wiki at https://github.com/mojolicious/mojo/wiki, which contains a lot more documentation and examples by many different authors. So many authors. So many examples. You will not run out of reading material, bestie. 📚

🫶 SUPPORT 🫶

If you have any questions the documentation might not yet answer, don't hesitate to ask in the Forum at https://forum.mojolicious.org, or on IRC at https://web.libera.chat/#mojo.

Like genuinely — the people there are nice, and asking is free. 💜

---

okay that's the whole page!! you read all of it, I'm so proud of you 😭✨ this was perl v5.42.0, dated 2026-07-15, straight from Mojolic...es::FAQ(3) — go build something iconic with it, mwah 💅💖