awesome-print/awesome_print · warning

Could not load '.aprc' from ENV['HOME']: #

Error message

Could not load '.aprc' from ENV['HOME']: #{e}

What it means

AwesomePrint prints this warning to stderr when it cannot load or apply your personal config file ~/.aprc. Every ap/ai call builds an AwesomePrint::Inspector, whose initialize calls merge_custom_defaults!: it Ruby-`load`s #{ENV['HOME']}/.aprc (inspector.rb:148) and then merges AwesomePrint.defaults into the options. Any StandardError raised in that process — ENV['HOME'] being nil inside File.join, a runtime error while executing .aprc, or a :color default that is not a Hash making @options[:color].merge! raise TypeError — is rescued, the original exception is embedded via #{e}, and the library silently falls back to built-in defaults. Nothing crashes; your custom defaults are simply ignored (a pure Ruby syntax error in .aprc raises SyntaxError, which this rescue does not catch at all).

Solutions

1. Read the tail of the message: the #{e} part carries the real underlying exception (e.g. 'no implicit conversion of nil into String' or 'uninitialized constant') — fix that cause, not awesome_print.
2. Verify the dotfile standalone: ruby -c ~/.aprc for syntax, then ruby -e "load File.expand_path('~/.aprc')" to reproduce any runtime error outside your app.
3. If HOME is unset (CI/container/service), set it before any printing: export HOME in the CI config, or add ENV['HOME'] ||= Dir.home early in boot.
4. Fix the defaults shape — :color must be a nested Hash: AwesomePrint.defaults = { color: { string: :redish }, indent: -2 }.
5. Still unexplained? Rename ~/.aprc to ~/.aprc.bak and re-run; if the warning disappears, bisect the dotfile line by line.

Example fix

# before (~/.aprc) — :color is a Symbol, merge_options! raises TypeError on every ap
AwesomePrint.defaults = { color: :blue, indent: 2 }

# after — :color is a Hash, loads cleanly
AwesomePrint.defaults = { color: { string: :blue }, indent: 2 }

# Run once at boot, before the first ap/ai call
aprc = File.join(ENV['HOME'].to_s, '.aprc')
if File.readable?(aprc)
  RubyVM::InstructionSequence.compile_file(aprc) # surfaces SyntaxError early, with a line number
  load aprc                                       # surfaces runtime errors now, not on every print
end
if AwesomePrint.defaults.is_a?(Hash) && AwesomePrint.defaults.key?(:color) && !AwesomePrint.defaults[:color].is_a?(Hash)
  raise ArgumentError, 'AwesomePrint.defaults[:color] must be a Hash'
end

def valid_aprc_defaults?
  d = AwesomePrint.defaults
  d.nil? || (d.is_a?(Hash) && (d[:color].nil? || d[:color].is_a?(Hash)))
end

raise 'bad .aprc defaults shape' unless valid_aprc_defaults?

When it happens

Trigger: Calling ap(anything) or object.ai in a process where ENV['HOME'] is nil (File.join(nil, '.aprc') raises TypeError: no implicit conversion of nil into String); a ~/.aprc whose Ruby raises StandardError when loaded, e.g. referencing an app constant undefined outside the app (NameError); AwesomePrint.defaults = { color: :blue } (non-Hash :color) making merge_options! at inspector.rb:140 call @options[:color].merge!(:blue) (TypeError); File.readable? raising Errno (EACCES/ENOENT) because $HOME points to an unreadable or stale path.

Common situations: CI runners, Docker containers, cron jobs, or systemd services where HOME is unset or scrubbed from the environment; a .aprc tuned inside a Rails console (referencing Rails/app constants) then used in plain ruby or irb; hand-edited .aprc with a typo or wrong defaults shape; shared dotfiles copied between machines with different users and permissions.

Related errors

• (Object doesn't support #ai)

AI-assisted analysis of awesome-print/awesome_print@8a7ff0aaba (2026-08-23). Data as JSON: /api/errors/633145db27047b66. Report an issue: GitHub.

Appendix: source

Thrown at lib/awesome_print/inspector.rb:166

      dotfile = File.join(ENV['HOME'], '.aprc')
      load dotfile if dotfile_readable?(dotfile)
    end

    def dotfile_readable? dotfile
      if @@dotfile_readable.nil? || @@dotfile != dotfile
        @@dotfile_readable = File.readable?(@@dotfile = dotfile)
      end
      @@dotfile_readable
    end
    @@dotfile_readable = @@dotfile = nil

    # Load ~/.aprc file with custom defaults that override default options.
    #---------------------------------------------------------------------------
    def merge_custom_defaults!
      load_dotfile
      merge_options!(AwesomePrint.defaults) if AwesomePrint.defaults.is_a?(Hash)
    rescue => e
      $stderr.puts "Could not load '.aprc' from ENV['HOME']: #{e}"
    end
  end
end

View on GitHub (pinned to 8a7ff0aaba)