Troubleshooting FAQ

Changes not showing up?

Were the changes in the .env, config files, or route files? 404 errors on recently added pages?

Try using php artisan optimize. If the site stops work at all, run it a second time.

Were the changes in css or images?

Try hard-refreshing your page (cmd + r for mac, ctrl + r for windows) or clearing your browser cache to see if they show up.

Initial Setup Common Issues

Root composer.json requires php ^7.4 but your php version (8.1.6) does not satisfy that requirement

You probably downloaded the wrong version of XAMPP!

Go to XAMPP's Downloads page and make sure you grab the version that matches the php version in your composer.json.

Extension Installation Common Issues

extension_tracker.php: syntax error, unexpected ';', expecting ']'

Because of the way github will do the conflicts in this file, it's really common to accidentally drop closing brackets and commas. You'll want to double check that every [ has a ],.

Ways to Troubleshoot on Local

Use the dd function

You should never use this on your server as it can easily expose information to your users, but it can be an invaluable way to see what data is being passed around when debugging an issue. When you place dd($variableName); somewhere in the code, when that line gets hit, it outputs the contents of whatever you passed to it out to your screen and completely stops all other code execution.

This is helpful in two main ways: 1. Seeing what data is being passed around - often bugs arise because of very specific data situations so being able to get an insight into what data is causing the issue can go a long way. 2. Stopping code execution can help locate what line is throwing an error - if the dd function never outputs before you get an error on screen, that means the line causing issues came before the line where you put the dd. You can keep moving the output line around until you're able to identify exactly which line caused you problems.

500 Errors - How to find and read your logs

500 errors are some of the most common errors you'll encounter on your site. If you are in your production server, they'll show up with very little information to inform you what has happened.

There are two main ways to get more information

1. Re-produce the error on your local environment, which should have error verbosity turned on. (Don't have a local? Go make one)
2. Find the error in your log files

Finding the error in your log files can be a little confusing if you've never done it before, so we'll walk through that here.

1. Navigate in your file manager to /storage/logs/ from your root LK folder
2. Find the file named with today's date
3. Open the file and scroll all the way to the bottom

At that point you should see a bunch of lines that look something like this ([...] added to represent bits that were removed for brevity):

#47 /[...]/laravel/framework/[...]/Pipeline.php(167): [...]\\PreventRequestsDuringMaintenance->handle(Object(Illuminate\\Http\\Request), Object(Closure))
#48 /[...]/laravel/framework/[...]/Pipeline.php(103): [...]\\Pipeline->Illuminate\\Pipeline\\{closure}(Object(Illuminate\\Http\\Request))
#49 /[...]/laravel/framework[...]/Kernel.php(141): [...]\\Pipeline->then(Object(Closure))

Notice the lines are numbered! What you'll want to do is carefully scroll up until you see those numbers count down to #0. We don't want to go past this set of lines and into the next error up, so it's important to not scroll through them too quickly or it'll be easy to miss.

When you get to #0 it'll look like this:

[stacktrace]
#0 [...]

And will have one additional line above that. That's your error message. It'll have a timestamp in front of it, and that's what you'll want to pay attention to, to try to solve the error, or copy into the discord so that others can help you parse what it means.

How to Read a 500 error

Most 500 errors will give you two important pieces of information - a variable name, and a file name.

An example of a 500 error:

Trying to get property 'name' of non-object (View: \site\resources\views\[...]\create_edit_submission.blade.php)

create_edit_submission.blade.php is the file where something is going wrong, and name is the variable, or function where things aren't working as expected.

While it's good to then go double check that template file to see if anything looks out of the norm, often template errors are occurring because of an issue deeper in the code. Tutorial: Adding Fields to Users/Characters/Etc has a great explanation about how the different parts of Lorekeeper hand-off to each other to explain how you can start to trace issues from a template to their cause.

Common Sources of 500 Errors

Deleted Entities

Whether it's a character, item, currency, or any other 'entity' in Lorekeeper, it's rare to delete one, and doing so can cause issues in parts of the application that don't have robust checks against something not existing. This is especially true when you start adding extensions to the mix. If you've deleted something recently and it's remotely related to the page giving you a 500 error, it's a good bet that it's the cause. If you're not sure how to fix it, then it's a good candidate for asking about in the discord server, as it can be very case by case!

Types of LK Errors

Trying to get property 'name' of non-object

This means that the code is trying to use a variable or function with the quoted name like object->name or object->name() but 'object' isn't an object type. That means it could have a string (text) content, or more often is set to null. Solving this issue generally involves figuring out why the wrong thing has been stored as 'object'.

Undefined Offset: 1

This means that the code is trying to access an array with a specific accessor string like array[$variable] where variable would contain the offset listed in the error or like array['1'] where the code is very deliberately accessing a specific value. In either case it means that that value name does not exist in the array, and debugging this error requires figuring out why something didn't get populated that likely should have been.

Git Issues

git pull: You have divergent branches and need to specify how to reconcile them.

Don't run the commands that git lists here. It's warning message isn't helpful.

What's happening instead is that when git tries to do a pull, it does two steps. It starts with git fetch and then it tries to intelligently decide whether it should do a git merge or a what git calls a "fast-forward" as the second step of the pull. (It's ok if you don't fully understand what those mean.)

The important part is that if git can't figure out which it should do on its own it gives you this warning.

Unless you're doing something really unusual you're probably either pulling in updates from the core lorekeeper, or an extension. In this case we already know we want to do a git pull. So instead of the usual pull command you'll want to click the "terminal" button in source tree (or if you're already in command line then no need), and run git merge reponame/extension/branchname and then you should be able to carry on as you would have before.