> For the complete documentation index, see [llms.txt](https://tk-scripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tk-scripts.gitbook.io/docs/tk_housing/common-questions-and-problems.md).
# Common questions & problems
Answers to the questions server owners ask most about Housing on a FiveM server, and fixes for common Housing errors.
## Common questions
How do I add properties?
Run [/addproperty](/docs/tk_housing/commands.md#addproperty) in game. Its wizard places a new property with a shell, IPL or MLO interior, and no restart is needed. These players can run it:
* Admins: players with the `command` ace or a group in `Config.AdminGroups` (default `admin`), while `Config.AllowAdmins.createProperty` is `true`.
* Real estate agents: players whose job and grade are in `Config.Jobs.realEstate`. The defaults are the jobs `real_estate` and `realestate` from grade `0`, so put your server's real estate job name there.
* Members of a real estate business whose grade has the `createProperty` flag, only when `Config.RealEstateBusiness.acquisition.mode` is `'create'` or `'both'`. The default `'purchase'` lets businesses buy and resell properties but not create them.
`Config.PropertyList.agents` (default `'both'`) sets whether job agents, business members or both count as agents. To start from a ready list of addresses instead, set `Config.UsePremadeProperties = true` in `config/properties.lua`; the `Config.Properties` entries appear on start, and you edit them in game with the property editor.
How do I add new interiors?
Add a shell in game: run [/shelleditor](/docs/tk_housing/commands.md#shelleditor) as an admin, choose Add house shell or Add garage shell, enter a config key, a label and the shell's model name (Test checks that it loads), capture the exits inside the shell and save. The editor writes the entry into `config/interiors.lua`. Start the resource that streams the shell before `tk_housing` in `server.cfg`, restart `tk_housing`, and the interior can be picked in the property editor.
An IPL or MLO interior that players teleport into is added by hand. Entries go in `Config.HouseInteriors`, or `Config.GarageInteriors` for a garage:
```lua
my_shell = {
model = `my_shell_model`,
label = 'My Shell',
exits = {
{label = 'Door 1', coords = vec4(0.0, 0.0, 0.0, 0.0)},
},
},
my_apartment = {
isIpl = true,
label = 'My Apartment',
exits = {
{label = 'Door 1', coords = vec4(-1000.0, -500.0, 50.0, 90.0)},
},
},
```
A shell's exit `coords` are an offset from the shell; an IPL's are world coordinates inside it, and its own map resource must load it. After a restart, `/shelleditor` can capture the rest of an IPL's exits, spots and elevator floors; [Interiors](/docs/tk_housing/config.md#interiors) lists every field. Keep a key once properties use it, or entering them prints `Property references a houseInterior key that is missing from Config.HouseInteriors` in the F8 console.
Why do I have fewer shells than the showcase?
The default `config/interiors.lua` needs only the [K4MB1 Starter Shells](https://k4mb1maps.com/product/5015840). Its other K4MB1 entries need the matching K4MB1 packs, and the property editor hides every interior whose model no started resource streams. You can also add other shells, use IPL interiors, or build your own with the [Shell Creator](/docs/tk_housing/commands.md#shellcreator).
How do I add my own furniture?
Add an entry such as `{price = 1000, label = 'My Chair', model = 'my_chair_model', uses = {'sit'}}` to a category table of `Config.Furniture` in `config/furniture.lua`, and start the resource that streams the model before `tk_housing`. Add to the existing category table; a second table with the same category name replaces the first. [Furniture catalog](/docs/tk_housing/config.md#furniture-catalog) lists the optional fields.
Can a property have a garage?
Yes. In the [/addproperty](/docs/tk_housing/commands.md#addproperty) wizard, give the property a garage interior and its entrance, or for an MLO a garage area and garage doors. To store a car, drive it to the garage entrance and enter from the driver's seat.
Can new players get a starter apartment?
Yes. Fill in `Config.StarterHousing.building` in `config/config.lua` and set `enabled = true`; each new character then gets a unit in that building when they load in. From your multicharacter or spawn script, call [giveStarterProperty](/docs/tk_housing/exports/server.md#givestarterproperty), or [setPropertyOwner](/docs/tk_housing/exports/server.md#setpropertyowner) to hand over a specific property.
How do I delete a property or take one back?
Open [/adminhousing](/docs/tk_housing/commands.md#adminhousing) as an admin: it deletes one or several properties, owned or not, and clears or changes an owner. In the server console, `removepropertyowner 12` frees property `12`, and `removeunusedproperties 60` deletes properties nobody has entered for 60 days; type the numbers without `< >`. A premade property comes back on the next start unless you also remove its entry from `Config.Properties`.
Does it work on Qbox?
Yes. Qbox runs the QBCore files, so set `Config.Framework = 'qb'`.
How do I upgrade from Housing V2?
Back up the database, install V3 without importing `tk_housing.sql`, and copy your V2 values into the V3 config files. Players keep their properties, furniture and garage vehicles; [Upgrade from Housing V2](/docs/tk_housing/setup.md#upgrade-from-housing-v2) has the steps.
Can I translate it?
Yes. English, Finnish and French ship with it. Copy `locales/en.lua` to a file such as `de.lua`, change `Locales['en']` on its first line to `Locales['de']`, translate the texts and set `Config.Locale = 'de'`.
Can break-in alerts go to my dispatch script?
Yes. Break-in alerts come from the alarm dispatch add-on (`Config.Security.alarms.dispatch.enable`, default `false`), which owners buy for a property with an alarm. `Config.Dispatch = 'tk'` or `'cd'` sends them to `tk_dispatch` or `cd_dispatch`; for another dispatch, tablet or phone script, call its alert export in `ReportBreakIn` in `server/main_editable.lua`.
Why do doors in my custom shell not open?
`server.cfg` is missing `setr game_enableDynamicDoorCreation "true"`. Add it as in [Housing installation](/docs/tk_housing/setup.md#install) and restart the server.
Can players build walls in an MLO?
No. Walls, floors and stairs can be placed only in custom shells. An MLO property gets its area, entrances and doors from the tools in the `/addproperty` wizard, and IPL interiors with a `customization` list get style choices.
Can I use my own garage script?
Yes. `Config.Garage.menu = 'jg-advancedgarages'` opens JG Advanced Garages in property garages; for another script, set `'custom'` and open its menu in `OpenGarageMenu` in `client/main_editable.lua`.
How do I give players furniture from another script?
Call the [giveFurniture](/docs/tk_housing/exports/server.md#givefurniture) server export. With the default `Config.Furnishing.acquisition = 'instant'`, only pieces marked `exclusive = true` in `config/furniture.lua` can be given.
Why does the weather change while I am inside?
`Config.Weather` does not match your weather script, so `tk_housing` cannot pause it. Set it to your script, or to `'custom'` and add your script's pause call to `SetWeatherSync` in `client/main_editable.lua`.
## Common problems
### Shell models are not loaded
When a player enters or previews a property, the F8 console prints:
```
Shell models are not loaded, make sure you have installed K4MB1 Starter Shells (link in README.txt)
```
The default interiors in `config/interiors.lua` use the K4MB1 Starter Shells, and that resource is missing or not started.
* Install the [K4MB1 Starter Shells](https://k4mb1maps.com/product/5015840) and `ensure` them before `tk_housing` in `server.cfg`.
* To use other shells, change the `model` of each entry in `Config.HouseInteriors` and `Config.GarageInteriors`.
### Players cannot enter a property
The player sees `Could not load the interior, please try again`, and the F8 console prints:
```
[tk_housing] Entry failed (model): shell model MODEL_HASH (config entry INTERIOR_KEY) is not loaded - check the model in Config.HouseInteriors/Config.GarageInteriors and that the resource streaming it is started.
```
`MODEL_HASH` is the shell's model hash and `INTERIOR_KEY` its entry in `config/interiors.lua`. No started resource streams that model. Start the shell resource before `tk_housing`, or give the property another interior in the property editor.
### Players fall through the map in a shell
After entering or previewing a property, the player drops through the shell or lands on its roof, with no error. The interior's exit `coords` in `config/interiors.lua` are not an offset from the shell: they are world coordinates, or a placeholder `vec4(0.0, 0.0, 0.0, 0.0)`.
1. Run [/shelleditor](/docs/tk_housing/commands.md#shelleditor) and open that interior.
2. Capture its exits again while standing inside the shell, then save.
3. Restart `tk_housing`.
### Entering a property shows a lib error
The F8 console prints:
```
error during NUI callback enterHouse: @tk_housing/client/main_editable.lua:141: attempt to index a nil value (global 'lib')
```
`Config.NotificationType = 'ox'` or `Config.UseOxLib = true` uses `ox_lib`, but `tk_housing` does not load it. Uncomment `'@ox_lib/init.lua',` in `shared_scripts` of `fxmanifest.lua` as in step 6 of [Install](/docs/tk_housing/setup.md#install), and start `ox_lib` before `tk_housing`.
### Custom shells have missing walls or stairs
The F8 console prints one of these:
```
Custom shell is missing some props because their models failed to load, walls or doors may be missing
Stair collision model missing, stairs will have no collision. Update housing_props and make sure it is started
```
The building pieces come from `tk_housing_props`, which is missing, outdated or started after `tk_housing`.
1. Download the latest `tk_housing_props` from the [Cfx.re Portal](https://portal.cfx.re/assets/granted-assets) and replace the folder.
2. In `server.cfg`, put `ensure tk_housing_props` before `ensure tk_housing`.
### Furniture is missing from the shop
The furniture menu lists fewer pieces than `config/furniture.lua`, and the F8 console prints:
```
Hid furniture models that the game has no archetype for. Remove or fix them in config/furniture.lua
```
The line is followed by the number of hidden pieces and their models. No started resource streams those models: many catalog models come from `tk_housing_props`, and your own pieces from their pack.
* Install `tk_housing_props` from the [Cfx.re Portal](https://portal.cfx.re/assets/granted-assets) and `ensure` it before `tk_housing`. If your Portal does not list it, open a ticket in the [TK Scripts Discord](https://discord.gg/YndnF9tkqu).
* For your own pieces, start their resource before `tk_housing`, or fix the `model` names.
### Shells cannot be saved to the resource folder
When `tk_housing` starts or a shell is saved, the server console prints one of these:
```
Custom shells could not be saved in the data folder, so they are saved in shells.json instead. They still work. To fix this, check that the folder RESOURCE_PATH/data exists and the server is allowed to save files in it
The server is not allowed to save files in RESOURCE_PATH, so custom shells are saved in the server database instead. They still work. This usually happens when the files were uploaded with a different login than the one the server runs under. To fix this, ask your host to let the server save files in that folder. On your own Linux server, log in as the user that starts the server and run: sudo chown -R $USER RESOURCE_PATH
The server is not allowed to save RESOURCE_PATH/config/interiors.lua. This usually happens when the files were uploaded with a different login than the one the server runs under. To fix this, ask your host to let the server save files in that folder. On your own Linux server, log in as the user that starts the server and run: sudo chown -R $USER RESOURCE_PATH
```
`RESOURCE_PATH` is the `tk_housing` folder. The `data` folder is missing, or the server's login may not write files in `tk_housing`. Shell Creator shells still work, but the shell editor cannot save until the last line is fixed.
1. Create a `data` folder inside `tk_housing`; upload tools often skip an empty folder.
2. If a line still prints, follow it: ask your host to let the server write that folder, or run the `chown` command on your own Linux server.
3. Restart `tk_housing`. Shells saved in the meantime move back to `data/shells.json`.
### In-game photos not working
Taking a listing photo in the property creator prints this in the server console, and picture frames offer no in-game photo:
```
No fivemanage token set, can't take photo. If you are the server owner, add one in config/server.lua, refer to tk_housing documentation
```
`ConfigSV.FivemanageToken` in `config/server.lua` is empty. Add a token as described in [Set up property photos](/docs/tk_housing/setup.md#set-up-property-photos).
### Furniture previews unavailable
Opening the furniture menu shows:
```
Furniture previews unavailable (screenshot-basic missing)
```
The game could not take the thumbnails directly, and `screenshot-basic` is not started as the fallback. Add `ensure screenshot-basic` before `ensure tk_housing` in `server.cfg`.
### Storages do not work on QBCore
Opening a storage prints this in the server console:
```
Config.Inventory is "default" which only works with Config.Framework = "esx", set Config.Inventory to "qb_old", "qb_new" or "ox" in config/config.lua
```
`'default'` is the ESX inventory. In `config/config.lua`, set `Config.Inventory` to `'qb_old'`, `'qb_new'`, `'ox'` or `'qs'` to match your inventory.
### House keys stay disabled
When `tk_housing` starts, the server console prints:
```
Config.Keys.enable is on but Config.Inventory is 'default'. Physical house keys need an inventory that supports item metadata, so cutting and holding keys stays disabled until Config.Inventory is set to something other than 'default'
```
Keys are items with metadata, which the ESX default inventory cannot hold. Set `Config.Inventory` to your inventory, and add the `house_key` item from [Housing installation](/docs/tk_housing/setup.md#install).
### Wardrobes or mirrors do nothing
Using a wardrobe or mirror prints this in the F8 console:
```
Clothing script is not supported, open client/main_editable.lua and edit OpenWardrobe to add it
```
`Config.Clothing` names a script that the code does not know.
* Set `Config.Clothing` to one of the 12 values listed beside it in `config/config.lua`.
* For another script, open its menu from `OpenWardrobe` and `OpenAppearance` in `client/main_editable.lua`.
### Menus show raw text keys
When `tk_housing` starts, the server console prints:
```
Config.Locale is set to a locale that has no locales/*.lua file. The menu will show raw keys
```
No file in `locales/` matches `Config.Locale`. Set `Config.Locale` to `'en'`, `'fi'` or `'fr'`, or to the name of a locale file you added under `locales/`.
### Real estate agents cannot add properties
A player running `/addproperty` sees:
```
You do not have permission to create properties
```
With `Config.RealEstateBusiness.enabled = false` the line is `You are not a real estate agent`. The player is not an admin, has no job and grade in `Config.Jobs.realEstate`, or is in a business that cannot create properties.
* Job agents: put your server's real estate job name and lowest grade in `Config.Jobs.realEstate`, and keep `Config.PropertyList.agents` at `'job'` or `'both'`.
* Business members: set `Config.RealEstateBusiness.acquisition.mode` to `'create'` or `'both'` (default `'purchase'`), and give the member's grade the `createProperty` flag.
* Admins: give the player the `command` ace or a group in `Config.AdminGroups`, then have them reconnect.
[addproperty](/docs/tk_housing/commands.md#addproperty) lists every rule for the command.
### The V2 upgrade cannot rename columns
When the server starts after an upgrade from V2, the server console prints:
```
[tk_housing] migration WARNING: the rows were written but the old columns could not all be renamed. This is usually a MariaDB dump on MySQL 8, where json_valid CHECK constraints block the rename. Drop those constraints by hand and restart. Until then this runs again every boot and writes the old values back over newer changes
```
A `could not rename tk_housing_properties.linking_doors to door_links` warning has the same cause, and no properties load until it is fixed. The database came from MariaDB and keeps `json_valid` CHECK constraints that MySQL 8 enforces.
1. Back up the database.
2. Run `SHOW CREATE TABLE tk_housing_properties;` and note the name of each `CHECK (json_valid(...))` constraint.
3. Drop each one with `ALTER TABLE tk_housing_properties DROP CHECK constraint_name;`.
4. Restart the server.
### The V2 upgrade verification failed
The server console prints:
```
[tk_housing] migration: verification FAILED. Some properties do not match (see the VERIFY MISMATCH lines above). The old data is kept and can still be recovered. Do NOT run housingdropbackups yet
```
Some furniture or vehicles did not match the V2 data. The `VERIFY MISMATCH` and `migration WARNING` lines printed before it name each property. Keep the `*_legacy` columns, do not run `housing_dropbackups`, and open a ticket in the [TK Scripts Discord](https://discord.gg/YndnF9tkqu) with those lines.
### Old properties cannot be entered after the V2 upgrade
When `tk_housing` starts, the server console prints:
```
Config.HouseInteriors entry "LABEL" has no key, so saved houses cannot use it. Give it one like name = { ... } in config/interiors.lua
```
`LABEL` is the entry's label or model. V2 listed interiors without names, and V3 finds a V2 property's interior by its key. In `config/interiors.lua`, write each entry you copied from V2 as `my_shell = { model = ..., label = ..., exits = { ... } },` with a unique name, then restart `tk_housing`. V3 matches the waiting V2 properties to those entries on every start.